Special considerations when connecting to Jira

The following special conditions apply when connecting to a self-hosted server or cloud based Jira instance.

  1. When attempting to connect to a Jira cloud instance with single sign-on (SSO) or basic authentication you must use an API Token as your password. (See https://confluence.atlassian.com/cloud/api-tokens-938839638.html for details.) Jira no longer supports the use of primary account credentials (like passwords) for basic authentication. (See https://developer.atlassian.com/cloud/jira/platform/deprecation-notice-basic-auth-and-cookie-based-auth/ for details.)

  2. When attempting to connect to a self-hosted Jira server instance with SSO you must configure your Jira server and SSO with the auth_fallback option. For details, please check the documentation for Jira and the SSO product you use.


    Once the above has been configured, Jira can fall back to local account passwords for authentication and the Jira / Polarion connector will be able to authenticate correctly.

  3. When attempting to connect to a Jira server instance with mutual or two-way authentication you need a keystore with a client certificate.

    1. Create a new keystore from the Jira client certificate with the same password as the certificate's password.

    2. Create a new entry in the user account vault of Polarion with the same password.

    3. Then add the following property to the polarion.properties file.

      com.siemens.polarion.jiraconnector.connectionCheckMutualTls =[server],[path],[alias],[user]

      • server: The server URL.

      • path: The path to the keystore.

      • alias : The certificate alias in the keystore.

      • user : Key entry in the vault with the password to the keystore.


You can define settings for several servers. Each server setting is separated by a semicolon and the configurations of each server setting are separated by a comma. You must use either the .jks or .pkcs12 file formats for the keystore.


The following example defines two different server configurations:


This may have security ramifications for your Jira project and you should implement the following security tips:

  • Only allow local Jira user accounts for people who need access to all Jira projects as well as the Polarion integration.

  • If you want greater access with more control, then set up special local accounts that can only access your target project.

Query language and formatting

JQL Query (Jira): A JQL (Jira Query Language) query can be used like a Work Item query to filter entities in Jira.

For the JQL Syntax please consult the official Jira documentation under https://confluence.atlassian.com/display/JIRA/Advanced+Searching.

Jira Formatting - (What's preserved and omitted when a Jira project is synchronized):

When synchronizing rich-text from Jira to Polarion, the Connector will use the conversion to HTML provided by Jira. This will accurately render the rich-text in Polarion for most Jira formatting, including all of the formatting listed below.

When synchronizing rich-text from Polarion back to Jira only the formatting listed below will preserved. (All other formatting will be removed.)


Formatting Preserved










Icon check


Icon failed


Icon information










Text color

(Characters placed before and after the target text.)

The following can also be synchronized with Jira:

  • Tables

  • Images and image references. (If you want to make an image reference on the Polarion side, the attachment link should have same label as its file name.)


Formatting omitted:

  • All other Jira formatting that is not listed in the above table.

  • All formatting done within Microsoft Word.

  • Formatting changes within a single word. (For example, Polarion)

  • Formatting that begins in the middle of one word and ends in another. (For example, polarion alm tool.)

Sync Jira Epic Links with Polarion

Assigning User Stories to Epics is common practice in Agile projects. Polarion and Jira do this in different ways:

  • In Polarion it's usually done by using a link role like Parent or Implements.

  • In Jira, it is done using the Epic Link field.

(The Epic Link field in Jira.)

If you are synchronizing both Epics and User Stories between Polarion and Jira, you'll probably also want to synchronize the links between Epics and Stories.

  1. 1. Add a field mapping in the type-specific Field Mapping section for User Stories.

  2. Click Edit on the right, then click Add.

  3. Enter the link role used in Polarion as the Left Value, LINKED_EPIC as the Right Value and click OK.


    Make sure that the link role is configured in Polarion and LINKED_EPIC is in all caps.

  4. Click Save at the top.

Sync Jira Links to Hyperlinks

You can also synchronize Jira links (both regular and Epic) to hyperlinks in Polarion:

  1. First, define an Attribute Mapping from Links to Hyperlinks. (Unidirectional – From Right to Left.)

  2. Then define a Value Mapping for each link type that you want to synchronize with Polarion, mapping the link type to a link role defined in Polarion.


If you don't map a link, no hyperlink will be created for that link type.

Mapping of Sync Pairs

Beginning with Polarion version 20 R1, changes were made to Polarion's support of mapping of Sync Pairs for Jira Cloud, due to changes in the Jira Cloud REST API. New Sync Pair mappings to Jira Cloud should observe the new field naming, described below. Existing mappings will need to be changed or replaced.


Currently, only mappings to Jira Cloud are affected. On-premise installed versions of Jira are not affected, and no change to existing mappings is necessary.

You can check the Jira instance type at: <jira-url>/rest/api/latest/serverInfo.

  • For on-premise versions: "deploymentType": "Server"

  • For Cloud versions: "deploymentType": "Cloud"

The name field of the User object is not present in the Jira Cloud API now. It is replaced by field accountId.

You can make this change in your existing mapping configuration(s) by editing the relevant Sync Pair(s) in Polarion project Administration, or in the underlying configuration file <project_directory>/.polarion/synchronizer/configuration.xml.

Fields accountId or name can be retrieved from: <jira-url>/rest/api/latest/user/search?username=<username>.

For additional information see: https://developer.atlassian.com/cloud/jira/platform/deprecation-notice-user-privacy-api-migration-guide/#user