Map types, fields, and values

After you've tested both connections as described in Create and configure a Synchronization Pair, 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 defined in 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.

Define type mapping

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.

  1. In the Actions column of the Type Mapping section, click Create New.

  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. Select third-party system's equivalent of the Polarion type specified in the Left Type column, so that the fields and attributes of these two types can be synchronized.

    4. Repeat the foregoing steps if there are more types that need to be synchronized.

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 Task items are to be synchronized, specify a query that returns only the Task Work Item type.

Define field mapping

After mapping the Work Item types, you can configure how fields of Polarion Work Items are mapped to fields or attributes of the equivalent artifacts 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.

  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. For example, the Title field of Polarion Work Items might be matched with a field with the same name in the third-party system, or another field that is the equivalent.

  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 third-party system field you select here. 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 in the third-party system is also changed 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 value of the Title field 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 field named Task Category for the Task type, for example — specify the mapping in the last subsection of Field Mappings.

Tip:
  • Warning:

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

Define value mapping

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.

  1. Click the Edit link in any field mapping to display a dialog box in which you can set value mappings.

  2. Click Add in the dialog box to add a new value mapping pair.

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

  4. When you have finished all the mapping, click Save at the top of the page to save the Synchronization Pair.

    5. You should now be able run synchronization to synchronize data between Polarion and the configured third-party system.