Conflicting Field Options Sync

Atlassian native select-list fields and similar field types require that all labels be distinct and unique. For each unique label, an Option ID is generated in Jira, and the app maps these Option IDs to Datasource IDs as defined in the field configuration.

Data conflicts can occur if there is an overlap of labels, such as when the same label is used for different Datasource IDs, because Jira does not permit duplicate labels within the same field. This often happens when an Option ID is disabled, but its label is reused for a different Jira Option ID, leading to conflicts due to Jira's requirement for unique labels.

Conflict Message Description

When a data conflict occurs, the error message appears as follows:

SelectionStrategyException: Conflicts: XXXXXX due to conflict with xxxxx:XXXXXX

Here,

XXXXXX: Represents the conflicting Jira option ID or label in Jira.

xxxxx : Indicates the specific Jira option ID or label that is causing the conflict.

This error arises when there are duplicate labels assigned to different Jira option IDs, violating Jira's requirement for unique labels.

Understanding Conflicts

To understand more about how a label conflict can arise, let us check the following example:
We have the following datasource and field configuration setup:

Datasource State 1:

{
    "result":[
        { "id": 1, "name": "Original 1"},
        { "id": 2, "name": "Original 2"}
    ]
}

Dictionary Field Options Sync Setup

Select List: $.result[*]
Unique ID: $.id
Label: $.name

A synchronisation of this datasource and field configuration will result in the following states:

Custom Field State 1:

Internal Mapping State 1:

In this initial state, Jira Option ID 701 is mapped to id: 1, name: Original 1, and Jira Option ID 702 is mapped to id: 2, name: Original 2.

Now, assuming some time has elapsed, the data source is updated as follows:

Datasource State 2:

{
  "result":[
      { "id": 2, "name": "Original 2"},
      { "id": 3, "name": "Original 3"}
  ]
}

A synchronisation of this datasource and field configuration will result in the following states:

Custom Field State 2:

Internal Mapping State 2:

Here, Original 1 is disabled, but still mapped to Jira OptionID 701. Original 3 is added as a new label which has Jira OptionID 703

Conflict Scenario: Insert Conflict

Now, assuming some time has elapsed, the data source is updated as follows:

Datasource State 3a:

{
  "result":[
      { "id": 2, "name": "Original 2"},
      { "id": 3, "name": "Original 3"},
      { "id": 4, "name": "Original 1"},
  ]
}

From the last state of the field, Jira OptionID 701 is disabled but its value Original 1 is now tried to be used for a new option with the DatasourceID 4.
Conflict: Attempting to insert id: 4, name: Original 1 results in a conflict because Original 1 is already used by Jira OptionID: 1.

Conflict Scenario: Update Conflict

Now, assuming some time has elapsed, the data source is updated as follows:

Datasource State 3b:

{
  "result":[
      { "id": 2, "name": "Original 2"},
      { "id": 3, "name": "Original 1"},
  ]
}

• Conflict: Changing Original 3 to Original 1 results in a conflict since Original 1 already exists for another ID which is disabled (OptionID 701).

Resolving Conflicts

To address the conflicts caused by duplicate labels in Jira Option IDs, you can use the following methods:

Method 1: Clear and Realign Mapping

1. Navigate to the App Dashboard:

   • Go to App > Status > Actions.

2. Clear and Realign:

   • Select Clear and Realign Mapping. (see screenshot below)

Impact: This action will remove the internal mapping without affecting any issue selections or custom field option labels. Any upcoming synchronization will attempt to establish a fresh mapping by utilizing existing labels to repair the state.

Method 2: Identify and Resolve Disabled Values

1. Access the Jira Fields:

   • In the App, go to Available Jira Fields.

2. Find the Custom Field:

   • Locate the custom field used for Field Options Sync.

3. Check External Links:

   • Click on the External link icon at the right end of the field. (Refer to the below screenshot for guidance.)

4. Open Contexts and Default Values:

   • Click the three dots (⋮) at the right end and select Contexts and Default Value.

   • In this section, you can identify which values are disabled and causing the conflict. By recognizing these disabled values, you can resolve the issue by renaming them and ensuring that their labels are unique.

By following these steps, you can effectively manage and resolve conflicts with your datasource labels.

Conclusion

Atlassian's native select-list fields and similar types require unique labels in Jira, preventing conflicts. Data conflicts arise when duplicate labels are used for different Datasource IDs, violating Jira's label uniqueness rule. The error message for conflicts includes details like conflicting Jira Option IDs or labels causing the issue. Resolving conflicts involves methods like clearing and realigning mappings or identifying disabled values in Jira fields.