Planning your Polarion Mappings to Jira (via OSLC)
Siemens Polarion provides a robust and flexible method of linking artifacts internally as well as externally. While most teams are familiar with the customization of the internal Polarion artifact types and link types, the usage of external links via OSLC may be a little more challenging. The intention of this guide is to help you design how to best leverage the configuration of Polarion with Jira (via OSLC).
OSLC in the Enterprise
What OSLC does very well is commonizing the artifact types that we link across repositories. Rather than be overly granular, the OSLC standard domains simplify the way we present artifacts. In the standard, we describe specific domains that detail out both elements and the relationships we create. In this sense, we formalize the vocabulary of the connections across our enterprise. This makes it easier for us to consider how to connect diverse tools simply and easily.
The core domains that are the focus of most ALM integrations are those of Change Management, Requirements Management, and Quality (Test) Management. These standard domains provide a vocabulary that allows tools to describe their artifacts and their links effectively while allowing tool vendors and users to customize their types and workflows within these standard integration foundations.
Linking Polarion and Jira
Linking Polarion and Jira requires the identification of the OSLC relationships that should take place between the tools. This should be based on your objectives and process implementations for your teams.
OSLC and Jira
What OSLC Connect for Jira provides is the implementation of the OSLC Core and the Change Management Domain for Jira. Every Jira Issue becomes an OSLC Change artifact in this implementation. Support of this standard allows Jira issues to connect to test artifacts, requirements artifacts, architecture artifacts, and change artifacts in patterns (link types).
While users can customize their Jira schemes internal to the Jira repository, each Jira issue is logically an OSLC Change externally. Jira will expect an external repository to select one or more of these domains to support and enable the standard link types for that domain.
The major configuration option provided relative to linking is the disallowing of non-preferred link types for a given Jira artifact type. This allows the restriction of the standard rather than the expansion of the standard.
OSLC and Polarion
Polarion provides a fully flexible OSLC Foundation, including mapping any Polarion artifact and link to an OSLC type (standard or custom). This flexibility can provide tremendous value, but it also can introduce additional complexity configuring your Polarion system to collaborate with other tools. By default all Jira Issues are OSLC artifacts, Polarion artifacts by default are not OSLC artifacts. This requires you to explicitly identify the types and relationships to support.
How to Plan your Jira and Polarion integration
For those interested in connecting Jira and Polarion we can suggest the following planning steps that make configuration significantly easier.
Step 1: Understand the Role of Jira
In your enterprise, Jira will be representing Change artifacts. This is a simplifying criterion and will aid in the possible relationships that can be represented. As a guide, you can look at the link relationships that Jira artifacts can participate within OSLC.
Logically, this allows a user to identify their general types of artifacts and the links that may be supported.
Step 2: Identify what Polarion Artifacts Are to be Exposed
Review the Work Items defined in Polarion. This is defined in your workitem-type-enum.xml configuration file. The common view looks similar to the following:
It is only required to track the elements that you want to link to Jira. For elements that remain only in Polarion, you can leave these without an OSLC Mapping.
Step 3: Identify what OSLC types each artifact will be Exposed as
Once you identify your Polarion resource to be used, it is important to map these to formal OSLC types. Your selection is purely up to your team, however, we do encourage you to pick a choice that is most consistent with the usage you intend.
Basic OSLC Types
(Reference: https://open-services.net/specifications/vocabularies/ )
Basic Name | OSLC Name | Notes |
|---|---|---|
ChangeRequest | oslc_cm:ChangeRequest | See Usage Identifiers to Specialize (defect, planItem, task, and requirementsChangeRequest) |
Requirement | oslc_rm:Requirement | |
Requirement Collection | oslc_rm:RequirementCollection | A document or a set of requirements |
Test Plan | oslc_qm:TestPlan | |
Test Case | oslc_qm:TestCase | |
Test Script | oslc_qm:TestScript | |
Test Execution Record | oslc_qm:TestExecutionRecord | |
Test Result | oslc_qm:TestResult | |
Architecture Element | oslc_am:Resource | Generic Modeling Element |
[Note AM and QM not handled by Polarion in default Semantics and must be user created]
There may be some iteration with this step and the next step as they do impact the available relationships available to the Jira Issues.
OSLC Usage
For Change Requests, there is some specialization of the classification that is used on the type mapping. For more precise mappings use the oslcUsage attribute
Basic Name | OSLC Usage |
|---|---|
Defect | oslc_cm:defect |
Plan Item | oslc_cm:planItem |
Requirements Change Request | oslc_cm:requirementsChangeRequest |
Task | oslc_cm:task |
Default | oslc:default |
In most cases, the default classification is used in Polarion mapped elements. However, the categories will be used when creating links to Jira as these are the available selection dialog from Polarion and can be mapped in Jira.
Step 4: Identify what OSLC Links each artifact should support
For each of your mapped Polarion to OSLC Types, you must define what OSLC Links will be supported.
The OSLC Domains specifically define these relationships. As Jira supports the four main domains the following link types are supported. Their source is always considered to be the change artifact, with the target artifact type the type that you have defined in your mapping.
Standard Link Types
Source | Target | Link | Backlink |
|---|---|---|---|
Change Request | Requirement | oslc_cm:implementsRequirement Implements Requirement | oslc_rm:implementedBy Implemented By |
Change Request | Requirement | oslc_cm:affectsRequirement Affects Requirement | oslc_rm:affectedBy Affected By |
Change Request | Requirement | oslc_cm:tracksRequirement Tracks Requirement | oslc_rm:trackedBy Tracked By |
Change Request | Change Request | oslc_cm:relatedChangeRequest Related Change Request | oslc_cm:relatedChangeRequest Related Change Request |
Change Request | Change Request | oslc_cm:affectsPlanItem Affects Plan Item | oslc_cm:affectedByDefect Affected By Defect |
Change Request | Change Request | oslc_cm:tracksWorkItem Tracks | oslc_cm:trackedWorkItem Contributes To |
Change Request | Test Case | oslc_cm:testedByTestCase Tested By Test Case | oslc_qm:testsChangeRequest Tests Development Item |
Change Request | Test Execution Record | oslc_cm:blocksTestExecutionRecord Blocks Test Execution | oslc_qm:blockedByChangeRequest Blocking Defect |
Change Request | Test Result | oslc_cm:affectsTestResult Affects Test Result | oslc_qm:affectedByChangeRequest Affected By Change Request |
Change Request | Test Plan | oslc_cm:relatedTestPlan Related Test Plan | oslc_qm:relatedChangeRequest Related Change Request |
Change Request | Test Case | oslc_cm:relatedTestCase Related Test Case | oslc_qm:relatedChangeRequest Related Change Request |
Change Request | Test Execution Record | oslc_cm:relatedTestExecutionRecord Related Test Execution | oslc_qm:relatedChangeRequest Related Change Request |
Change Request | Test Script | oslc_cm:relatedTestScript Related Test Script | oslc_qm:relatedChangeRequest Related Change Request |
Change Request | Architecture Resource | oslc_cm:relatedArchitectureElement Elaborated By Architecture Element | jazz_dm:elaborates Elaborates |
It is possible, and often common for each artifact to support several link types.
Step 5: Identify how these OSLC should be mapped to Polarion Links
Polarion provides additional flexibility of other tools of remapping link types to custom link type names. For each of the links you identified in Step 4, you are able to map to existing Polarion link types or create new link types.
We recommend that configurations use the common OSLC labels for these links as they best exemplify the reverse link in Jira and prevent confusion. This may require the creation of new Polarion link types.
Step 6: Document your Design
It is important to document your linking design. It will be valuable in both communicating your process as well as for the Polarion admin implementing the configuration. (Or even SodiusWillert support if you have a question).
Two common ways to document that we have good results with are:
Table
In a table, I can capture the intention of the relationships and the ids that are important for the configuration. It is a little less visible, but can be purposeful.
Graph
A graph can convey critical information and provide a bit more of a visual representation such as the following with similar information
Step 7: Configure Polarion
Use your design to update your Polarion Linked Data Mapping.
In your, Linked Data Mapping update the type-mappings with your Workitem Id to OSLC type mapping.
<type-mapping oslcType="oslc_cm:ChangeRequest" oslcUsage="oslc:default" polarionType="issue"/>
<type-mapping oslcType="oslc_cm:ChangeRequest" oslcUsage="oslc:default" polarionType="changerequest"/>
<type-mapping oslcType="oslc_rm:Requirement" oslcUsage="oslc:default" polarionType="softwarerequirement"/>
<type-mapping oslcType="oslc_rm:Requirement" oslcUsage="oslc:default" polarionType="systemrequirement"/>
<type-mapping oslcType="oslc_qm:TestCase" oslcUsage="oslc:default" polarionType="softwaretestcase"/>
<type-mapping oslcType="oslc_qm:TestCase" oslcUsage="oslc:default" polarionType="systemtestcase"/>
<type-mapping oslcType="oslc_qm:TestCase" oslcUsage="oslc:default" polarionType="testcase"/>Which need to match your definition of your polarion workitem types
And your link-role mappings
<link-role-mapping linkRole="implements" oslcLinkProperty="oslc_rm:implementedBy"/>
<link-role-mapping linkRole="track" oslcLinkProperty="oslc_rm:trackedBy"/>
<link-role-mapping linkRole="affects" oslcLinkProperty="oslc_rm:affectedBy"/>
<link-role-mapping linkRole="tracks" oslcLinkProperty="oslc_cm:tracksWorkItem"/>
<link-role-mapping linkRole="relatesTC" oslcLinkProperty="oslc_qm:relatedChangeRequest"/>
<link-role-mapping linkRole="testsCR" oslcLinkProperty="oslc_qm:testsChangeRequest"/>Which must match your Polarion link roles
Recommendations
A few last recommendations.
Most teams have found simple relationships serve themselves best
Use basic OSLC names for your link types
Most teams have found common organization schemes (rather than unique project mappings) server them best.
Practice Mappings initially in a single project