Edit field mapping

ALM Octane and ALM or Jira fields are mapped to specify pairs of fields with synchronized data. Field mapping includes specific field value mapping (for list fields), as well as the direction in which the data is synchronized.

For details about mapping user list field values, see Map user list fields.

Note: You must always run an integrity check after modifying a link's configuration. We also recommend running a simulation to prevent errors occurring in the actual synchronization.

For details, see Step 6: Run synchronizations.

Field mapping overview

When you first create a link, some system fields and field values are mapped automatically, as long as the field or field values have not been modified. To view an example, see Examples of automatically mapped fields: ALM or Jira defects.

On the link configuration Field Mapping tab, view the automatic mapping and modify it if necessary, and map user defined and other optional fields. Mandatory fields must be mapped to synchronize records correctly. How do I get to the Link Configuration page?

For requirement links, select the sub node for each requirement type in the tree to view its field mapping.

Tip: Before you start synchronizing, it is highly recommended that you read Field mapping guidelines. For additional recommendations before synchronizing, see Prepare for ALM synchronization.

Back to top

Automatically map similar fields

To begin mapping, in the link configuration Field Mapping tab, click the Automatically map fields button (in edit mode).

Fields that have the same name and type in both sides of the mapping will be mapped automatically. For example, if ALM Octane and Jira both have memo fields named Description, these fields will be mapped to one another.

When done, run an integrity check as described in Step 6: Run synchronizations.

Back to top

Notes about Type, Attributes, and Required in the Field Mapping tab

The Type and Attributes columns are populated automatically. The red asterisk indicating a field is Required is set by the system as well.

Type. If the type is Reference, that means this field links the entity to an item created in ALM Octane. For example, a release, a sprint, a user, or another backlog item. The possible values for this field depend on the items defined in the system.

Attributes. Some fields, such as IDs, are marked in the Attributes columns as R (Read only). This means the field values are set by the system and cannot be entered by the user, or set via synchronization. For example, the ALM Octane Defect ID is a read only field. You cannot map it to synchronize bidirectionally. However, you can map it for unidirectional synchronization, setting a custom ALM Octane ID field in the ALM or Jira endpoint.

Required. You cannot manually set a field as required for synchronization.

Back to top

Map a pair of fields or define constant values

On the link configuration Field Mapping tab, view the existing mapping and modify it if necessary. How do I get to the Link Configuration page?

Click Edit Link to modify settings, and Save Link to save your changes.

  1. Above the mapping grid, toggle between showing ALM Octane Fields and ALM/Jira Fields to determine how the fields are listed in the grid.

  2. Select the row for the field you want to map, and define the following:

    1. In the Direction column , select whether you want to map the field from ALM Octane to ALM or Jira, vice versa, or as bidirectional.

      If the field has no corresponding field in the other endpoint, select Constant.

    2. In the mapped field column (ALM Octane Field or ALM/Jira Field, depending on how you are viewing the fields) select a field from the dropdown list. Use the search box to filter the fields displayed.

      If you are mapping a constant value, enter the value in the corresponding column cell. The constant value is assigned to the field when ALM Octane Synchronizer creates new entities, and is not updated in subsequent synchronizations.

      Example: If you created a Creation Method user-defined field in ALM to distinguish between entities created directly in ALM and those synchronized from ALM Octane, enter created by ALM Octane Synchronizer as the mapped constant value. For details, see Prepare for ALM synchronization.

    If you need to map multiple fields in the opposite endpoint, click in the Multi-Mapping column. When you do this, your direction options are limited to prevent conflicts.

    The Field Mapping grid supports the following actions:

    Action Description

    Select columns to view

    Use the column selector above the grid to select the columns displayed.

    Refresh grid

    Above the grid, click to refresh the grid after making changes to the list of fields in either endpoint. For example, refresh the grid after adding new values to a list field.

    Sort or group by column

    Hover over a column heading and click the arrow to sort or group the grid by the selected column. This menu also lets you hide this column from the grid.

    Show only specific fields

    The grid footer lets you filter the grid by fields that are mapped or unmapped, or are causing errors or warnings in integrity checks. You can also select to show all fields.

    At the bottom of the grid, select:

    • Mapped to view only mapped fields
    • Unmapped to view only unmapped fields
    • Errors to view only fields with mappings that will cause errors, and will also prevent synchronizations from running
    • Warnings to view only fields with mappings that may cause errors but will not prevent synchronization from running
    • Total Items to view all fields, regardless of mapping status

Back to top

Additional field mapping tasks

Define a Dominant Endpoint to determine the source of the synchronized value in case of conflicts.

  1. On the Field Mapping tab, select a pair of mapped fields to view additional properties on the right.

  2. On the right, expand the Mapping Properties section.

  3. Select the endpoint you want to define as the dominant endpoint.

Mapping specific field values is relevant only for mapped list fields. Select and map values and mapping directions for each field in the endpoints.

Caution: If you have different numbers of values in the field for each endpoint (such as 5 values in ALM Octane and 6 values in ALM), bidirectional value mapping may result in some data loss when records are synchronized back and forth. For details and recommendations, see Guidelines for mapping specific field values.

  1. On the Field Mapping tab, select a pair of mapped fields to view additional properties on the right.

  2. On the right, expand the Values section.

  3. Map specific values in the each field to corresponding values in the opposite field, as well as their directions. If relevant, you can map one of the values to an empty string.

    Values are automatically mapped by name in the case of simple lists (strings, numbers), releases, labels and teams. For users, automatic mapping is done according to email address.

  4. Define a Default value to use when the field value is empty in the source endpoint, but mandatory in the destination endpoint.

    Default values replace the empty values, and help to avoid synchronization errors. Leave this field empty if you do not want to use a default value.

    Note: ALM Octane Synchronizer uses the default value only when creating a new entity, not when updating.

    The Default value field is displayed only:

    • in the field mapping properties for the endpoint where the field is mandatory.

    • if the field is mandatory in the destination endpoint.

    Possible warnings on this field:

    If the Default value field is highlighted in red, run an integrity check and review the warnings it provides. As long as the integrity check does not contain errors, you may be able to ignore some of these warnings. They warn of potential issues that could arise during synchronization.

    For example:

    • The length of the field in ALM Octane is shorter than the length of the mapped Jira field.

    • In ALM Octane, the list has fixed set of possible values, but in ALM the list is not set to verify values, and will accept any value.

Example of mapping field values: ALM Octane Phase and ALM or Jira Status

  1. On the Field Mapping tab, select a pair of mapped fields to view additional properties on the right.

  2. Expand the Field Properties section to view the available properties, such as the field schema names in either endpoint, or whether the field is read-only.

    The displayed properties differ, depending on the type of field you select.

You can export and import mappings to save time. For example, suppose you have custom fields on a defect in JIRA whose values you have already mapped. You can then export those mappings from one workspace to another and not map them manually every time.

To export mapping for future use:

Select a link in the left pane and choose the Export Field Mapping menu command. Alternatively, select a link and then click the Export field mapping button in the Field Mapping tab.

The field mapping is exported in JSON format.

You cannot export in Edit mode.

To import mapping from a JSON file or from another link:

  1. In Edit mode, select a link in the left pane and choose the Import Field Mapping menu command. Alternatively, select a link and then click the Import field mapping button in the Field Mapping tab.

  2. Use the import dialog to specify the desired mapping to import.

    • If you are on a defect or release link you cannot import from a backlog link.

    • If you are on a backlog link you can only import from another backlog link. You will need to specify the sublink (user story, feature, epic) whose mapping you want to use for import.

    Note that importing overrides existing mapping definitions on the selected link. After importing you can revert changes using the Cancel Edit button.

  3. To apply the imported mappings to the link, click Save link.

To unmap a pair of ALM or Jira and ALM Octane fields, when there are multiple fields mapped in one endpoint to a single field in the opposite endpoint, click in the Multi-Mapping column.

To remove a single field mapping (a pair of ALM or Jira and ALM Octane fields that have one field in each endpoint), click in the mapped field.

Back to top

See also: