Planning your Polarion Mappings to Jira (via OSLC)
Siemens Polarion provides a robust and flexible method of linking artifacts internally and externally. While most teams are familiar with customizing the internal Polarion artifact types and link types, using external links via OSLC may be more challenging. This guide intends to help you design how to best leverage Polarion's configuration 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 both elements and the relationships we create. In this sense, we formalize the vocabulary of the connections across our enterprise. This makes it easier to consider connecting diverse tools.
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
OSLC Connect for Jira provides the implementation of the OSLC Core, Change Management, and Quality Management Domain for Jira. Every Jira Issue becomes an OSLC Change artifact (by default) 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). Optionally users can map Jira Artifacts to QM types and use alternative links for those resource types.
While users can customize their Jira schemes internally, each Jira issue is assigned a OSLC type 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.
OSLC and Polarion
Polarion provides a fully flexible OSLC Foundation, including mapping any Polarion artifact and linking to an OSLC type (standard or custom). This flexibility can provide tremendous value, but it also can introduce additional complexity in configuring your Polarion system. By default, Polarion artifacts are not OSLC artifacts. This requires you to identify the types and relationships to support explicitly.
How to Plan your Jira and Polarion integration
For those interested in connecting Jira and Polarion, we can suggest the following planning steps to make configuration significantly easier.
Step 1: Understand the Role of Jira
In your enterprise, Jira will be representing Change artifacts. This simplifying criterion will aid in the possible relationships that can be described. As a guide, you can look at the link relationships that Jira artifacts can participate in within OSLC.
OSLC Change relationships to other types
Logically, this allows users 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 impact the relationships available to Jira Issues.
OSLC Usage
For Change Requests, there is some specialization of the classifications that are used. 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 (or complexity) having the OSLC link types mapped to a Polarion link type. For each link identified in Step 4, you can map to existing Polarion link types or create new ones.
We recommend that configurations use the OSLC labels for these links as they best exemplify the reverse link in Jira and prevent confusion. This may require creating new Polarion link types.
Step 6: Document your Design
It is essential to document your linking design. It will be valuable in 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 relationships' intention and the important ids 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