Configure Synchronization

This topic covers how to configure a connection to a supported system like Atlassian Jira, HP ALM or DOORS via a Polarion Connector.

You will need to:

Data Backup

Before you begin using any Connector(s), be sure to have your system backup administrator include the Connectors data folder in routine backups. Losing Connector data will result in items being recreated rather than updated when systems are synchronized.

For details, please refer to Administrator's Guide, System Maintenance, Backing up Polarion Data: Connectors Data.

TIPS

  1. Be sure to read this entire section before configuring and creating a synchronization pair, so you become familiar with all the capabilities.

  2. Spend some time planning out your data synchronization between Polarion and the third-party systems. As already stated, ensure you have a backup process in place, in the event you need to return to a previous state.

Configure Connections

A "Connection" refers to a specific third-party server containing the data you want to replicate. Objects from the third-party system are identified based on their ID and the connection that was used to synchronize them.

TIPS

  • If you specify multiple connections for the same third-party system you will duplicate items.

  • Only a single synchronization can run with a specific connection at any given time.

Creating a New Connection

To create a new Connection:

  1. Open the Polarion project that corresponds to third-party's project that you want to synchronize data with. (You will need administrator permissions for this project.)

  2. Open Administration, and in Navigation select Connectors to access the Connectors page.

  3. In the Connections section of the page, click Add Connection in the Actions column.

  4. In the Create new connection to dialog, select the third-party system to connect to and click Next.

    (The list contains the systems currently supported by Polarion Connectors.)

  5. In the Create New Connection To [SYSTEM] dialog, specify the Connection ID that identifies items from a specific server and the fields required by the third-party system.

    (Use an ID name that helps you identify that unique connection.

  6. Click Create to verify and finish configuring the Connection.

Create Links Between Different Projects

Because items are identified by their ID and the connection that creates the links between projects needs the same connection, use a global connection to synchronize linked items to different Polarion projects. (This ensures that the links between the items are recreated in Polarion.) For example, to import links from defects in Project B to requirements in Project A. In this case, defining the mapping of the link parameter for the defect type is sufficient.

If the items are not in one sync pair, it may be necessary to execute the synchronization twice, because links cannot be created when there is no target for them yet. The items must be created during the first sync, and then on next sync they will be linked.

Create a Global Connection Template

Connections can be configured globally for an entire repository. When created in the global scope, Connections become Connection Templates, which can be reused in different projects. The login credentials for Connection Templates are not stored in the User Account Vault. Users can enable Connections defined in the global scope in any project by supplying login credentials. You can create entirely new Connection Templates, or save any existing project-scope Connection configurations as global Connection Templates.

To create an entirely new Connection Template, follow the same steps as outlined previously in Creating a New Connection, but instead of opening a project, open the Repository.

To reuse and existing Connection as a global Connection Template:

  1. Open the Connection for editing in the Connectors topic of Administration.

    Use the drop-down control by the Save button, and select Save As.

  2. In the Save Connection Configuration dialog, select the Create new configuration option, and in the Scope field, select Global.

  3. Specify an ID for the new Connection configuration and click Save.

Configure a Synchronization Pair

The Sync Pair Configuration page provides settings for Polarion and the third-party server connections, data propagation, and data mapping.

Create a Synchronization Pair

Before Creating a Synchronization Pair

Make sure that you've created a Connection before you create and define Synchronization Pairs.

A Synchronization Pair defines how a specific type of information is exchanged and synchronized between Polarion and the target third-party system configured in the Connection. Polarion includes several Synchronization Pair templates that are pre-configured with the commonly required settings, needed to facilitate the configuration of new Synchronization Pairs. You can optionally save Synchronization Pairs that you create and configure, as templates.

To create a new Synchronization Pair:

  1. In the Synchronization Pairs section of the page, click Add Sync Pair in the Actions column.

  2. In the Template field, select the template for the type of synchronization you are creating. The list of templates is filtered according to the setting of the Connect to field, so you may need to set that field in order to select the right template.

    Note

    If you haven't created a synchronization pair before this, then no templates will be available.

  3. Specify a unique identifier for the new Synchronization Pair in Sync Pair ID. This ID can be specified in Jobs that run this Synchronization Pair. Example: Jira Sync 1

  4. Select a Connection in the Connect to field. The list in this field is populated with the names of all existing Connections.

  5. Click Create to create the Synchronization Pair configuration.

    The Sync Pair Configuration page for the new Synchronization Pair loads displays the pair's settings and data mappings.

    The sections that follow will cover these settings.

Configure Polarion Settings

In the Polarion Configuration section, set the following:

  • Account vault key (Required): The authentication key from the User Account Vault that contains a user name and password that the Connector can use to access the Polarion server.

    You may want to configure a new key specifically for use with Connectors, or even different keys for different Connectors if you connect Polarion to more than one third-party system. For details about Account Vault keys see: Configuring the User Accounts Vault.

    (The Account Vault configuration requires global administrator permissions.)

  • Query (Optional): But generally recommended. Enter Lucene query syntax to filter the Work Items that will be synchronized with the third-party system. For example, maybe only Task type items will be synced with JIRA. If that's the case, then you would specify a simple query like type:task. For Task items that are Open or Finished, you would need a more complex query: type:task AND (status:open OR status:done).

    Important:

    Once an item has been synchronized, it will continue to be synchronized until it does not match the query configured for Polarion and the query configured from the third-party system.

  • Live Document(Optional): Specified as space name/Document name. If specified, only Work Items from the specified Document in the specified space will be synchronized. The Document items are filtered according to the filter (if any), in the Query field.

  • Use title as root:(Optional): Check this option if the title of a Document should be treated as the root element in the synchronization.

    (The title itself will not be synced but all synced items will have it as an ancestor.)

When you've set the desired properties, test the settings using the Test Connection button, a green check mark appears if the configuration is valid as specified. A descriptive error message appears if a setting is incorrectly configured. This connection, and the one to the third-party system described below must succeed before you can proceed to complete the Synchronization Pair configuration.

Configure the Settings of the Connected System

To the right of the Polarion Configuration section there is another section with connection settings for the target third-party system. The fields vary depending on the system, but should be similar enough to Polarion's settings to recognize. (It is expected that you are familiar with the third-party system and understand the relevancy of the fields). Label semantics are taken from the third-party system. After you specify these settings, test the connection with the section's Test Connection button. This connection, and the one to the Polarion server described above, must succeed before you can proceed to complete the Synchronization Pair configuration.

General Settings

The settings in this section let you control the propagation of new items and deleted items between Polarion and the third-party system.

  • Propagate new items: Controls how new items are synchronized.

    • Bidirectional: New items created in Polarion will propagate to the third-party system and vice versa.

    • Left to Right: New items of the compatible mappedtype(s) created in Polarion will propagate to the third-party system, but new items created there will not propagate to Polarion.

    • Right to Left: New items created in the third-party system will propagate to Polarion, but new items created in Polarion will not propagate to the third-party system.

    • Disabled: Prevents all propagation of new items between the two systems. It is likely to be less commonly used than the other options.

      (Only if there's a case where the Synchronization Pair should only be applied to items created before the Sync Pair configuration.)

  • Propagate deletes: This setting works much like Disabled except that it controls how deleted items are synchronized.

Type and Field and Value Mapping

After you've tested both connections as described in the previous section, the Mapping section appears in the lower part of the page. There are two mappings to complete:

  • Type mapping: Maps one or more artifact types of your Polarion project to their equivalent artifact type in the third-party system's project.

  • Field mapping: Maps one or more Work Item fields of your Polarion project to their equivalents on the third-party system, and specifies the direction and precedence of synchronization.

First, map the Polarion Work Item type(s) you want to synchronize to their equivalents on the third-party system. Create a row in the Type Mapping section for every Work Item type you want to synchronize.

To define a Type mapping:

  1. Click Create New in the Actions column of the Type Mapping section.

  2. In Left Type, select a Polarion Work Item type in the list. This type will be synchronized with a third-party type specified in the Right Type column.

  3. In Right Type, select a third-party artifact type in the list. (The third-party system's equivalent of the Polarion type specified in the Left Type column, so that the fields/attributes of these two types can be synchronized.

  4. If more types need to be synchronized, create a new row in the Type Mapping section using Create New.

    TIP

    Make sure that you map all types that might be synchronized in accordance with the queries defined in the Polarion and third-party configurations. If you only want to sync specific types, you must configure the queries to filter your target types. For Polarion set the Query field in the Polarion Configuration section and have it filter for all types defined in the Type Mapping section. For example, if only Tasks are to be synchronized, specify a query for the Task Work Item type.

After mapping the type(s), you can configure how fields of Polarion Work Items are mapped to fields or attributes of the equivalent artifact(s) on the third party system. You do this in the Field Mappings section. You can specify field mappings applicable to all types, and field mappings applicable to specific types. The latter is especially needed if you want to synchronize one or more type-specific fields.

Field mappings also specify the synchronization direction, and in the case of bidirectional synchronization, the precedence.

To customize a Field Mapping:

  1. Select a value in the Left Field list. The list contains Polarion Work Item fields, and the one you select is to be matched with a field of the third party system: Title, for example.

  2. Select a value the Right Field list. The list contains names of fields or attributes of the third-party system. The field you selected in Left Column will synchronize with the selected field on the third-party system. For example, if the third-party system is JIRA and you selected Title in the previous step, then you would probably select Summary in this field.

  3. Select a value in the Direction list. This specifies if the synchronization is bi-directional, or only from Polarion to the third-party system (Left to Right), or only from the third-party system to Polarion (Right to Left).

  4. If you selected Bidirectional in the previous step, you should review and set Primary Direction. This is the direction that will be take precedence if there is a conflict. For example if the Title field is changed in Polarion and its equivalent is also changed in the third-party system between synchronizations, there will be a conflict when the next synchronization occurs.

    Choose which direction should take precedence. For example, if you select Left to Right, the Title value in Polarion will overwrite the changed value of the equivalent field or attribute in the third-party system during the next synchronization.

  5. Click OK when you finish the mapping. To define additional field mappings, click Create New in the Actions column and specify mappings for the fields, direction, and precedence.

If you want to map fields that are configured only for a specific Work Item type (a custom Task Category field for the Task type, for example), specify the mapping in the last subsection of Field Mappings.

TIPS

  • VERY IMPORTANT! Do not try to synchronize to the Type attribute since type is already mapped via the configured Type mapping. Overwriting the Type using a field mapping will cause unpredictable behavior.

  • The UI does not display which attributes are read-only, but you can check the sync execution log. It displays error messages when any attempt to overwrite a read-only attribute is made.

  • When synchronizing rich-text attributes like the Description in Polarion and Jira or Object Text in DOORS, you should also consider synchronizing attachments. (They might be referenced or embedded within the synchronized rich-text and will otherwise be missing.)

Within field mappings, you can also specify value mappings. This is required when you need to synchronize values like users in a field like Assignee, or an enumeration value in a field like Severity. Click the Edit link in any field mapping to display a dialog in which you can set value mappings. Click Add in the dialog to add a new value mapping pair. Specify the Polarion value in the Left field, and the third-party value in the  Right field. You can create multiple value mappings for any mapped field. The value that will be used in Polarion (left side) is the ID of the enumeration option, category or user. The value that will be used for the third-party (right side) depends on the system that you are synchronizing to.

TIP

If you are unsure about what value is used in the third-party system, start with synchronizing the value to Polarion without mapping it. Polarion will set the value to whatever is used in the third-party system and you can then define the value mapping based on that.

When you have finished all the mapping, click Save at the top of the page to save the Synchronization Pair. You should now be able to synchronize data between Polarion and the configured third-party system. You can do this either manually, as described in the next section, or by setting up a scheduled Job to run the synchronization automatically at an interval of your choosing.

Executing a Synchronization Pair

After you have created a connection and added a Synchronization Pair for it, you are ready to synchronize data between to two systems.

To explicitly invoke synchronization manually, click the Execute link for the Synchronization Pair on the Sync Configuration page. The progress and log of the synchronization can be seen in the Monitor topic of project Navigation. (For testing, it can be useful to open this topic in a different browser tab before executing the synchronization.) Look for the job named Synchronization of [SYNC PAIR NAME] (where [SYNC PAIR NAME] is the name of the Synchronization Pair executed).

As already mentioned, you can automate synchronization by creating a scheduled Job to execute the Synchronization pair at an interval of your choosing. You create jobs in the Scheduler topic of Global administration. For more information, see Configuring the Scheduler.

Job Configuration

In the Scheduler, you need to create a new <job> element. Since Synchronization Pairs are configured in the project scope, it is essential to specify the project ID in the scope attribute.

Example 1:

<job id="synchronizer" name="Connector Sync Job" scope="project:MyProjectID" cronExpression="0019?*MON-FRI">
    <syncPair>[SYNC PAIR ID]</syncPair>
</job>                       
                    

  • Use synchronizer as the value for the id attribute.

  • Use any meaningful string in the name. This is the name that will appear in the Scheduler's list of jobs.

  • In the above example, replace MyProjectID with the actual ID of the project that the Synchronization Pair to be executed is configured in.

  • The cronExpression attribute is optional. It's only used if you want the job to run automatically at some defined interval.

  • The <syncPair> element, replaces the [SYNC PAIR ID] of the actual ID of the Synchronization Pair that will be executed by this job. To avoid errors, open the Synchronization Pair configuration in another browser tab and copying the configured ID.

Example 2:

 <job id="synchronizer" name="Jira Sync 1" scope="project:elibrary">
    <syncPair>Jira - Defects</syncPair>
</job>
                    

Reusing Sync Pairs as Global Templates

Synchronization Pairs can be configured globally for an entire repository. When created in the global scope, Sync Pairs become Synchronization Pair Templates, that can be reused in different projects. Each Synchronization Pair Template must use an existing Connection defined in a Connection Template. You can create entirely new Synchronization Pair Templates, or save any existing project-scope Synchronization Pair configurations as a global Synchronization Pair Template.

To create an entirely new Synchronization Template, follow the same steps as outlined previously in the section Creating a Synchronization Pair, but instead of opening a project, open the Repository.

To reuse and existing Synchronization Pair as a global Synchronization Pair Template:

  1. Open the Synchronization Pair for editing in the Connectors topic of Administration.

    Use the drop-down control near the Save button, and select Save As.

  2. In the Save Synchronization Pair Configuration dialog, select the Create new configuration option, and in the Scope field, select Global.

  3. Specify an ID for the new Synchronization Pair configuration and click Save.

System Specific Instructions

HP QC or ALM Database

Connection Settings

When configuring a connection to HP ALM or Quality Center, you can optionally specify a direct connection to the SQL database using JDBC. While this connection is optional, it is not possible to access (read/write) links from tests to requirements, and between requirements, without it.

To successfully connect, you need to specify a value in the JDBC Connection String. This value can be derived from the Connection String in the DB Servers tab of HP ALM's Site Administration. When you enter the string into Polarion, replace mercury with jtds (for a Microsoft SQL database), or oracle:thin (for an Oracle Database).

Sync Pair Settings

Filter (HPQC): A filter in HPQC can be used like a Work Item query to filter entities in HPQC. The syntax for a filter is: field_id[filter]. For example a filter to have only entities with ids between 5 and 10 would be: id[>=5 And <11]. In the filter block the following operators can be used:

  • Comparison operators:<,>,<>,>=,<=,

  • Logical operators: and, or, not,

  • Literals: A string that represent the value of an expression. If a value contains spaces, it must be contained within single or double quotes. Literals can contain the '*' wild card.

  • Pairs of parenthesis.

Multiple filters can be combined using the AND or OR operator. For example the query id[>3] AND title['foo ba*'] is a valid query to filter out all entities with an ID larger than 3, and a title starting with foo ba.

Parent ID (HPQC): The ID of an entity in HPQC, that will be used to define a root element in HPQC. Every entity from Polarion will be put below this root element in HPQC, and only entities that are below this root element will be transferred from HPQC to Polarion. The parent ID can only be used for the "Requirement" HPQC entity type, since its the only element that supports hierarchies.

Jira

JQL Query (JIRA): A JQL (Jira Query Language) 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.)

Table 16.1. Preserved Formatting:

CharacterFormatting Preserved

+

Underline

*

Bold

_

Italic

-

Strike-through

(/)

Icon check

(x)

Icon failed

(i)

Icon information

??

Citation

^

Superscript

~

Subscript

{quote}

Block-quote

{color: }

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

Formating omitted:

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

  • All formating 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.

To synchronize Jira's "Epic Link" attribute with Polarion Work Item links:

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

  2. Click Edit on the right then click .

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

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

Note:

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

DOORS

Import Limitations and Recommendations

Before importing, read the Import Limitations and Recommendations section.

Connecting to DOORS

The connection to DOORS only requires the ID used to identify the target DOORS database. The connection is established from the DOORS client to Polarion by running a DXL script.

Click Connect to activate the connection and run the DXL script in a DOORS client (ToolsEdit) connected to the DOORS database containing the module you want to synchronize.

Note

  • While the script is running, the DOORS client will be locked until you close the connection.

  • Running the script from a Module can lock up the sync. (The connector might attempt to close the DOORS module.)

If you are planning to schedule the synchronization, run the DOORS client on a workstation where the connection can be kept active.

(See Scheduling Synchronization with DOORS for details.)

Creating a Sync Pair for Doors and Advanced Type Mappings
GENERAL SETUP:

When synchronizing with DOORS you typically want to synchronize Live Documents in Polarion to Modules in DOORS and include the structure in the specifications. This will allow you to easily control the mapping to Polarion Work Items, since they will be in the context of the Live Document you have chosen to synchronize to.

To synchronize the structure, one sync pair must be defined per Module/Live Document pair. Make sure that you configure the sync pair so that it points to a specific Live Document in Polarion and Module in Doors. (See Configure a Synchronization Pair for details.)

There are two ways you can configure a DOORS sync pair:
  1. Use the Module ID;

    1. Open the DOORS module you want to synchronize, go to Tools Edit DXL, then insert following script and run it:

      Module m = current
      print qualifiedUniqueID(m)
                      

    2. Put the value you get after execution of the script in the appropriate field in the Doors Sync Pair in Polarion.

  2. Use the Module URL;

    1. Choose the target module in Doors, then right-click to open the context menu and choose Properties.

    2. In the opened General tab click Copy URL beside URL.

    3. Paste the value in in appropriate field in the Doors Sync Pair in Polarion

TIP

Check the Use Title as Root option to sync Work Items below the first title in Polarion because it is usually a better representation of a DOORS Module’s structure. If you have additional content below the first title, depending on the synchronization pair settings, the sync operation may attempt to create objects in DOORS to synchronize this Live Doc.

You can set the Creation and Hierarchy directions in the following ways:

  • Right to Left: To replicate requirements from Doors to Polarion.

  • Left to Right: To send new Work Items from Polarion to Doors.

  • Bidirectional: To synchronize new requirements.

TYPE MAPPINGS:

Before beginning the mapping process, spend some time determining how you want the data mapped between DOORS and Polarion. The Synchronization will not create Polarion Work Item types and fields automatically. (They should all be created before you start mapping.)

The DOORS connector will treat objects without Object Text as Headings and other objects as Requirements.

Since DOORS does not differentiate between different types of objects in a module, it’s common practice to define the attribute type in DOORS.

These types can then be mapped via the Advanced type mappings dialog.

To access Advanced type mapping:

  1. Click next to Right Type.

  2. Select a Type Attribute from the drop-down box.

  3. All values of the selected attribute should now be available for type mapping.

Note

Mapping to the Work Item type heading will impose some limitations on the way that the structure can be represented in Polarion.

TIP

You can always choose to use a Work-item of type called something like Doors heading to replicate the DOORS structure verbatim inside of Polarion.

Field mappings will vary depending on your needs, but consider following DOORS specific suggestions:

  • When syncing any rich text attributes, you should also include attachments because the rich text fields might include embedded objects.

  • VERY IMPORTANT! Avoid syncing back Object Heading for non-heading Work Item types because Polarion will automatically populate the heading and returning these auto generated headings might not be desirable.

The connector will use the name of a DOORS option for Value mappings. Define Value mappings accordingly, especially when syncing an attribute to Doors. (Attempting to update an attribute with an invalid value will fail).

MAPPING LINKS:

Links can be synchronized from DOORS to Polarion by defining an attribute mapping from Relations to Linked Work Items.

By default, the link created in Polarion will use the relates_to link role. It can be configured by defining a value mapping from related_to in DOORS to the link role you want to use in Polarion.

Different roles can be used per Object or Work Item type by defining the attribute mapping for links in the Type-specific Mapping section.

Limitations
  • The same limitations as a DOORS Import apply.

  • Bidirectional synchronization of rich text can lead to loss of Polarion data because DOORS’ ability to store rich text is very limited.

  • Currently it is not possible to synchronize links added in Polarion to Doors.

  • When adding .rtf files containing OLE objects in Polarion, syncing them to Doors will result in the reversion of an attachment with an adjusted name (<Doors Attribute> <Index>.rtf)

Scheduling Synchronization with DOORS

When configuring synchronization with DOORS as a scheduled job, you must keep the DOORS client running in the background. It must be done on a workstation that can connect to the Polarion server and the DOORS server.

(The DOORS server must also have the DOORS client installed on it.)

The DOORS client can be executed as a scheduled job to ensure that the client is started automatically. (Just in case the workstation is restarted or the Doors client crashes.)

To add the scheduled DOORS connection:

  1. Create a C:\doorssync folder.

  2. Create a connect.dxl file and populate it with the connection script.

  3. Open the Task Scheduler Windows application.

  4. Click Create Task. (Named, for example, Doors Connection.)

  5. Name the task "Doors Connections" (for example), and set it to Run whether users is logged on or not.

  6. Click on the Trigger tab, click New, select At Startup from the Begin the task drop-down menu and click OK.

  7. Click New again on the Trigger tab, select On a Schedule from the Begin the task drop-down menu, click on Daily set up a time like the screenshot below and click OK.

  8. Both triggers should be listed and appear as Enabled in the Trigger tab.

  9. Click on the Actions tab and click New....

  10. Select Start a program in the Action drop-down box.

  11. Under Program/script: click Browse... and select the cmd.exe file. (C:\Windows\System32\cmd.exe).

  12. Add the following to the Add arguments field:

    (Replacing USER and PASSWORD with the credentials of the doors user you want to use for sync.)

    cmd /c ""C:\Program Files\IBM\Rational\DOORS\9.6\bin\doors.exe" -b connect.dxl -user "USER" -password "PASSWORD" -W nowait 1> doors.out 2> doors.err

  13. Add C:\doorssync to the Start in field: