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: )

Basic Name





See Usage Identifiers to Specialize (defect, planItem, task, and requirementsChangeRequest)



Requirement Collection


A document or a set of requirements

Test Plan


Test Case


Test Script


Test Execution Record


Test Result


Architecture Element


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



Plan Item


Requirements Change Request






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





Change Request



Implements Requirement


Implemented By

Change Request



Affects Requirement


Affected By

Change Request



Tracks Requirement


Tracked By

Change Request

Change Request


Related Change Request


Related Change Request

Change Request

Change Request


Affects Plan Item


Affected By Defect

Change Request

Change Request




Contributes To

Change Request

Test Case


Tested By Test Case


Tests Development Item

Change Request

Test Execution Record


Blocks Test Execution


Blocking Defect

Change Request

Test Result


Affects Test Result


Affected By Change Request

Change Request

Test Plan


Related Test Plan


Related Change Request

Change Request

Test Case


Related Test Case


Related Change Request

Change Request

Test Execution Record


Related Test Execution


Related Change Request

Change Request

Test Script


Related Test Script


Related Change Request

Change Request

Architecture Resource


Elaborated By Architecture Element



It is possible, and often common for each artifact to support several link types.

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:


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.


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


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