Skip to main content
Skip table of contents

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.

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.

CODE
 <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

CODE
<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

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.