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
![Screenshot 2024-07-23 at 14.39.42.png](../__attachments/1626505223/Screenshot%202024-07-23%20at%2014.39.42.png?inst-v=1a3ec3ad-33db-4627-8179-dd1fc7c6ae9a)
A synchronisation of this datasource and field configuration will result in the following states:
Custom Field State 1:
Jira OptionID | Label | state |
---|---|---|
701 | Original 1 | enabled |
702 | Original 2 | enabled |
Internal Mapping State 1:
Jira OptionID | FieldOptionSync ID |
---|---|
701 | 1 |
702 | 2 |
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:
Jira OptionID | Label | state |
---|---|---|
701 | Original 1 | disabled |
702 | Original 2 | enabled |
703 | Original 3 | enabled |
Internal Mapping State 2:
OptionID | FieldOptionSync ID |
---|---|
701 | 1 |
702 | 2 |
703 | 3 |
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
toOriginal 1
results in a conflict sinceOriginal 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
Navigate to the App Dashboard:
Go to App > Status > Actions.
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.
![Screenshot 2024-02-01 at 16.58.09.png](../__attachments/1626505223/Screenshot%202024-02-01%20at%2016.58.09.png?inst-v=1a3ec3ad-33db-4627-8179-dd1fc7c6ae9a)
Method 2: Identify and Resolve Disabled Values
Access the Jira Fields:
In the App, go to Available Jira Fields.
Find the Custom Field:
Locate the custom field used for Field Options Sync.
Check External Links:
Click on the External link icon at the right end of the field. (Refer to the below screenshot for guidance.)
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.
![Screenshot 2024-02-01 at 17.00.13.png](../__attachments/1626505223/Screenshot%202024-02-01%20at%2017.00.13.png?inst-v=1a3ec3ad-33db-4627-8179-dd1fc7c6ae9a)
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.