Polarion

Prerequisites

System Prerequisites

• API Enablement:

  • Polarion's REST API must be enabled in the polarion.properties file by setting the following property:

    • com.siemens.polarion.rest.enabled=true

  • You can find this file in Polarion installed directory at:

    • @POLARION_INSTALLATION_PATH@\polarion\configuration

  • Refer Polarion API Reference for more details.

• Enable Apache Axis Support for Polarion:

  To connect OpsHub Integration Manager with Polarion, you need to add a required library in Polarion instance.

  Why this is needed:

  The Polarion web service client used by OpsHub Integration Manager depends on Apache Axis. Without this library, the connection will not work.

  Steps:

  1. Download the required file

     • Download the axis-1.3.jar file from the Apache Axis 1.3 package available on Maven Repository.

     • Download link: axis-1.3.jar.

  2. Copy the file to the correct location

     • Place the downloaded file in the following folder: <opshub_installation_directory>\OpsHubServer\bundle_config\POLARION_LIB

User Privileges

• Create a user in Polarion that is dedicated for OpsHub Integration Manager. This user shouldn't perform any other action from Polarion's user interface.

• Following are the user privileges required:

1. The user must have access to the default SVN repository:

   • To grant user access to the default repository, refer Grant Permission To Access Repository.

2. The user must have the role of 'project_admin' in the project which they are going to configure in OpsHub Integration Manager.

   • To assign this role, refer Assign Role To User.

3. The user must have the following minimal permissions:

Access Level	READ Permissions	WRITE Permissions
Projects	Permission to VIEW	Permission to VIEW
REST API Endpoints	Permission to GET	Permission to GET Permission to PATCH Permission to POST Permission to DELETE (For attachments only)

• To check if the user has above permissions, refer to section Check API Permissions Required

System Configuration

Before you continue with the integration, you must first configure the Polarion system in OpsHub Integration Manager.

Refer to System Configuration for steps on how to configure the system. Refer to the screenshot below:

Polarion System Form Details

Field Name	When is the field visible	Description
System Name	Always	Provide a unique name for the Polarion system.
Instance URL	Always	Provide the Server URL of the Polarion instance. Format: http://[host name]:[port no] or http://[your_domain_name]. Example: http://10.13.27.200:8080.
User Name	Always	Provide the username of the dedicated user for Polarion API communication.
Personal Access Token	Always	Provide the Personal Access Token for the user specified in the "User Name" field. Refer to Access API Token section for details.
Instance Time Zone	Always	Provide the time zone of the host machine where Polarion is installed.
Metadata JSON	Always	Provide link metadata for Polarion workitem type in JSON format. For more details refer to Link Metadata Configuration. This same field is also used to declare custom fields for the Plan entity (refer to Plan Field Configuration) and to override the data type of Rich Text custom fields on a Test Run (refer to Test Run Field Configuration).
Base URL for Remote Link	Always	Provide a different instance URL of the Polarion instance. This URL will be used for generating the Remote Link. Note: If "Base URL for Remote Link" is empty, it will use default Instance URL to generate remote link if configured on integration.

Mapping Configuration

Map the fields between Polarion and the other system to be integrated to ensure that the data between both systems synchronizes correctly.

Refer to Mapping Configuration for steps on configuring field mappings.

Test Step Mapping (Advanced Mapping for Additional Fields)

When synchronizing Test Steps from or to Polarion, standard fields (like Step, Step Description, and Expected Result) can often be mapped directly. However, if your Polarion Test Steps contain Additional Fields (custom columns within the test step table), you must use Advanced Mapping (XSLT) to access and map them.

1. In the Mapping Configuration screen, click the Advanced Mapping toggle for the Test Steps field.

2. Use the provided XSLT template to map the standard steps, and assess the additionalFields node to map custom test step columns.

Mapping Detail (XSLT Snippet for ADO <-> Polarion):

<testSteps op_type="TestSteps">
    <xsl:for-each xmlns:xsl="http://www.w3.org/1999/XSL/Transform" select="SourceXML/updatedFields/Property/Steps/com.opshub.eai.tfs.common.TestStep">
        <com.opshub.eai.TestStep>
            <id>
                <xsl:value-of select="testStep/id"/>
            </id>
            <step>
                <xsl:value-of select="testStep/position"/>
            </step>
            <order>
                <xsl:value-of select="testStep/position"/>
            </order>
            <description>
                <xsl:value-of select="testStep/action"/>
            </description>
            <expected>
                <xsl:value-of select="testStep/expectedResult"/>
            </expected>
            <additionalFields>
                <stepAttachments>
                    <xsl:for-each select="eaiAttachment/OHAttachment">
                        <xsl:value-of select="fileName"/>
                        <xsl:if test="position() != last()">, </xsl:if>
                    </xsl:for-each>
                </stepAttachments>
            </additionalFields>
        </com.opshub.eai.TestStep>
    </xsl:for-each>
</testSteps>

Points To Be Considered

Rename Standard Column Behavior

If the internal name of the standard Test Step columns (such as Step, Step Description, or Expected Result) is renamed in Polarion, the following behavior will occur:

• Empty Standard Columns: During synchronization from the source system to Polarion, these standard columns will remain empty. No data will be populated in them.

• Data Fallback: The synchronization data intended for these renamed columns will instead fall into the Additional Column Details (Additional Fields) within the Test Step. You must use Advanced Mapping to extract or map them if needed.

Plan Field Configuration

Polarion does not provide any API to list the custom fields configured on a Plan. Because of this, if you want to synchronize a Plan custom field, you must declare it yourself in the Metadata JSON field on the Polarion system form.

Understanding Metadata JSON Input for Plan Custom Fields

This JSON is to be added in system form. Refer to section System Form configuration Add each Plan custom field as an entry under entities → plan → fields → custom:

{
  "entities": [
    {
      "internalName": "plan",
      "fields": {
        "custom": [
          {
            "internalName": "customRichText",
            "displayName": "customRichText",
            "dataType": "html",
            "mandatory": false,
            "readOnly": false,
            "systemSpecific": {
              "systemNativeDataType": "richText"
            }
          },
          {
            "internalName": "customLookup",
            "displayName": "customLookup",
            "dataType": "lookup",
            "mandatory": false,
            "readOnly": false,
            "lookUpValues": {
              "windows": "MS Windows",
              "linux": "Linux",
              "osx": "Mac OS X",
              "other": "Other"
            }
          }
        ]
      }
    }
  ]
}

Property	Description
internalName	Internal name (id) of the custom field, exactly as configured in Polarion. Refer to Get Custom Fields for Plan to find this value.
displayName	Name shown for the field in OpsHub Integration Manager's mapping screen.
dataType	The field's type. Supported values: text, numeric, boolean, date , date_string, lookup, html, wiki, user, link, reference.
mandatory	Set to true if the field is required in Polarion. Defaults to false.
readOnly	Set to true if the field cannot be written to. Defaults to false.
systemSpecific.systemNativeDataType	Only needed for rich text fields — set to richText so the value is sent to Polarion as HTML.
lookUpValues	Only needed when dataType is lookup — a list of "<internal id>": "<display value>" pairs, since Polarion does not expose an API to fetch a custom field's option list either.

Template Field

The Template field of a Plan can only be set when the Plan is created — Polarion does not allow it to be changed afterwards. While mapping the Template field, set its Sync When? option to Create (not the default Both). Refer to Sync When for steps.

Note: If Sync When? is left as Both, every update sync for that Plan will fail with a Polarion error.

Test Run Field Configuration

Polarion custom fields configured on a Test Run are discovered automatically — you do not need to declare them in the Metadata JSON.

Exception — Rich Text fields: Polarion's API response reports a rich text (HTML) custom field the same way it reports a plain text custom field, so OpsHub Integration Manager cannot tell the two apart on its own. If a Test Run custom field is Rich Text in Polarion, you must override its data type in the Metadata JSON field on the Polarion system form so it is synchronized as HTML instead of plain text.

Understanding Metadata JSON Input for Test Run Rich Text Fields

This JSON is to be added in system form. Refer to section System Form configuration Add an entry for the field under entities → testRun → fields → custom, with dataType set to html:

{
  "entities": [
    {
      "internalName": "testRun",
      "fields": {
        "custom": [
          {
            "internalName": "customRichText",
            "dataType": "html",
            "systemSpecific": {
              "systemNativeDataType": "richText"
            }
          }
        ]
      }
    }
  ]
}

Property	Description
internalName	Internal name (id) of the Rich Text custom field, exactly as configured in Polarion. Refer to Get Custom Fields for Test Run to find this value.
dataType	Set to html to override the field's discovered type.
systemSpecific.systemNativeDataType	Set to richText so the value is sent to Polarion as HTML.

Note: Only fields that are Rich Text in Polarion need to be listed here.

Template Field

The Template field of a Test Run can only be set when the Test Run is created — Polarion does not allow it to be updated later. While mapping the Template field, set its Sync When? option to Create (not the default Both). Refer to Sync When for steps.

Note: If Sync When flag is configured as Both, every update sync for that Test Run will fail with a Polarion error.

Integration Configuration

Set a time to synchronize data between Polarion and the other system. Define parameters and conditions, if any, for integration.

Refer to Integration Configuration for step-by-step instructions.

Criteria Configuration

If you want to specify conditions for synchronizing an entity between Polarion and the other system to be integrated, you can use the Criteria Configuration feature.

Navigate to Criteria Configuration to learn in detail about Criteria Configuration.

• To configure criteria in Polarion, integration needs to be created with Polarion as the source system. Set the Query as per Polarion's Lucene query syntax.

  • Refer to Polarion API Reference for more details on query format.

• While adding the criteria, user needs to add the internal names of the fields on which the criteria has to be applied.

  • Refer to Access Field Internal Name section for details.

• Given below are the sample snippets of how the Polarion queries can be used as criteria query in OpsHub Integration Manager:

Sample criteria:

Field name	Field internal name	Criteria description	Criteria snippet
Title	title	Sync items with title containing "API"	(title:*API*)
Status	status	Sync items where status equals "Open"	(status:open)
Created Date	created	Sync items created between 1 June 2025 to 30 June 2025	(created:[20250601 TO 20250630])
Status	status	Sync items where status is not reviewed	(NOT status:reviewed)
Severity	severity	Sync items where severity is either normal or blocker	(severity:normal OR severity:blocker)

Target LookUp Configuration

• Provide query in Target Search Query field such that it is possible to search the entity in the Polarion as the target system. In the target search query field, you can provide a placeholder for the source system's field value in the '@'.

• To learn in detail about how to configure Target LookUp, refer to Search in Target Before Sync section on Integration Configuration page.

• Overall, Target LookUp Query is similar to Criteria configuration, except that the value part contains a field name with '@' instead of static value.

• While adding the query, user needs to add the internal names of the fields on which the query is to be applied.

Sample target lookup query:

Field name	Field internal name	Target Lookup use case	Query snippet
Target Item ID	targetItem	Target Lookup on the item having the source entity's id in custom field called 'targetItem'	targetLookup:@oh_internal_id@

Known Behaviors and Limitations

• History based synchronization is not supported due to API unavailability.

• Comments:

  • Replies to comments or edits in Polarion will be synced as separate comments by OpsHub Integration Manager.

• Project Groups:

  • Project Groups are not visible in the Project mapping list due to API limitations; projects are listed individually.

• Test cases Work item:

  • Test Steps are supported. However, if your Test Steps contain custom columns or if a standard column has been renamed, you must use Advanced Mapping (XSLT) to access and map the additionalFields.

  • Synchronization of relationships between Test Steps and Test Records is not currently supported.

• Links

  • For link synchronization it is required to provide link metadata for Polarion entity types in JSON format in OpsHub Integration Manager.

    • Reason: API unavailability.

  • The Suspect and Revision properties of a link will not be explicitly synchronized due to API limitations as these properties are auto-populated by Polarion when links are added.

• Plan:

  • Attachments and comments are not supported for Plan, as Polarion does not provide them for this entity.

  • Custom fields on a Plan must be declared using the Metadata JSON field, since Polarion provides no API to fetch them. Refer to Plan Field Configuration.

• Test Run:

  • Polarion reports a Rich Text custom field the same way it reports a plain text one, so a Rich Text custom field on a Test Run must be declared in the Metadata JSON field, otherwise it will be synchronized as plain text instead of HTML. Refer to Test Run Field Configuration.

Appendix

Grant Permission To Access Repository

To make sure the user (Example, ID = automationtest) has access to the SVN repository:

• Update the 'access' file located at @POLARION_INSTALLATION_PATH@\data\svn, add the following entries:

  # Append automationtest to existing lists
   [groups]
   user = ..., automationtest
   
   [/]
   automationtest = rw
  
   [repo:/]
   automationtest = rw
  
   [repo:/.polarion/access]
   automationtest = rw

Assign Role To User

To assign user the role of 'project_admin':

1. Log in to your Polarion account as admin.

2. Go to the 'Administration' section by clicking on the settings icon in the top left-hand corner of your screen. Refer to the screenshot below:

   

3. Click 'User Management' -> 'Users' in the left pane. Refer to the screenshot below:

   

4. In 'Project Roles', give the user 'project_admin' role. For example, refer to the screenshot below for Role assigned to the user in Project 'Automation_Unit_Project':

   

Check API Permissions Required

To give user the relevant permissions that allows synchronization of entities:

1. Log in to your Polarion account as admin.

2. Go to the 'Administration' section by clicking on the settings icon in the top left-hand corner of your screen. Refer to the screenshot below:

   

3. Now, go to 'User Management' -> 'Permissions Management' -> 'By Role'. Here, make sure the following permissions are checked.

   

Get API Token

To get the API token for a user:

1. Log in to your Polarion account.

2. Go to the 'My Account' section by clicking on the settings icon in the top left-hand corner of your screen. Refer to the screenshot below:

   

3. Click 'Personal Access Token' in the top pane and copy the token value. Refer to the screenshot below:

   
4. Provide the toke details. Refer to the screenshot below:

   

Note:

• It is recommended to regenerate API token before it expires, to avoid unexpected processing failures in OpsHub Integration Manager.

Access Field Internal Name

To get the field internal names:

1. Log in to your Polarion account.

2. Go to the 'Administration' section by clicking on the settings icon in the top left-hand corner of your screen. Refer to the screenshot below:

   

3. Click 'Work Items' -> 'Custom Fields' in the left pane. Refer to the screenshot below:

   
4. The column named 'ID' contains internal names of the field. Refer to the screenshot below:

   

Get Custom Fields for Plan

To get the internal names of Plan's custom fields:

1. Log in to your Polarion account.

2. Go to the 'Administration' section by clicking on the settings icon in the top left-hand corner of your screen, then click 'Plans' -> 'Plan Custom Fields' in the left pane.

3. The column named 'ID' contains internal names of the field. Refer to the screenshot below:

   

Get Custom Fields for Test Run

To get the internal names of Test Run's custom fields:

1. Log in to your Polarion account.

2. Go to the 'Administration' section by clicking on the settings icon in the top left-hand corner of your screen, then click 'Testing' -> 'Test Run Custom Fields' in the left pane.

3. The column named 'ID' contains internal names of the field. Refer to the screenshot below:

   

Link Metadata Configuration

This section includes a sample Link Metadata JSON template used for configuring links in Polarion. Modify the template according to your requirements Link Metadata JSON Example:

{
   "entities": [
      {
         "internalName": "task",
         "relationship": {
            "linkTypes": [
               {
                  "linkType": "has parent",
                  "linkTypeInternalName": "parent",
                  "linkTypeDirection": "FORWARD",
                  "reverseLinkType": "is parent of",
                  "supportedAsSource": true,
                  "supportedAsTarget": true,
                  "mandatory": false
               },
               {
                  "linkType": "is parent of",
                  "linkTypeInternalName": "parent",
                  "linkTypeDirection": "BACKWARD",
                  "reverseLinkType": "has parent",
                  "supportedAsSource": true,
                  "supportedAsTarget": true,
                  "mandatory": false
               }
            ]
         }
      },
      {
         "internalName": "epic",
         "relationship": {
            "linkTypes": [
               {
                  "linkType": "has parent",
                  "linkTypeInternalName": "parent",
                  "linkTypeDirection": "FORWARD",
                  "reverseLinkType": "is parent of",
                  "supportedAsSource": true,
                  "supportedAsTarget": true,
                  "mandatory": false
               },
               {
                  "linkType": "is parent of",
                  "linkTypeInternalName": "parent",
                  "linkTypeDirection": "BACKWARD",
                  "reverseLinkType": "has parent",
                  "supportedAsSource": true,
                  "supportedAsTarget": true,
                  "mandatory": false
               }
            ]
         }
      }
   ]
}

The following steps describe how to populate the Link JSON metadata values for 'linkType', 'linkTypeInternalName', 'linkTypeDirection' and other related link properties. Steps: 1. Log in to your Polarion account. 2. Navigate to the 'Administration' section by clicking on the settings icon in the top left-hand corner of the screen. Refer to the screenshot below:

3. Navigate to 'Work Items' → 'Enumerations', open 'workitem-link-role-enum.xml', and select 'Edit'. Refer to the screenshot below for guidance.

4. Within the enumeration file: - The values listed under 'ID' represent the internal names of the links and should be mapped to the 'linkTypeInternalName' property in the JSON metadata. - The values under 'Name' and 'Opposite Name' correspond to the display names of the links and should be mapped to the 'linkType' property in the JSON metadata. - For entries under 'Name', the 'linkTypeDirection' property should be set to 'FORWARD', while for entries under 'Opposite Name', it should be set to 'BACKWARD'. - The values of 'supportedAsSource' and 'supportedAsTarget' must be set to 'true' because Polarion supports links in both directions. - The 'mandatory' property should be set to 'true' if the link is required, otherwise, it should be set to 'false'.