Merging & Converting Custom Fields Guide
- Hubert Kut
The Custom Field Merger in Doctor Pro for Jira helps admins streamline Jira configurations by merging redundant custom fields while preserving historical data or converting from one type into another. This reduces clutter, optimizes performance, and improves consistency across projects.
We have expanded the options for merging Jira custom fields, allowing for more flexibility in field transformations. The updated mappings are as follows:
Source Field Type | Allowed Target Field Types |
|---|---|
Single Select | Multi-Select, Short Text, Long Text, Single Select |
Read-Only Field | Read-Only Field, Short Text, Long Text (Multi-line) |
URL | URL, Short Text, Long Text |
User Picker | User Picker, Multi-User Picker |
Short Text (Text Field) | Short Text (1:1) |
Float | Float (1:1) |
Labels | Labels (1:1) |
Date Picker | Date Picker (1:1) |
DateTime | DateTime (1:1) |
Cascading Select | Cascading Select (1:1) |
Multi-Checkboxes | Multi-Checkboxes (1:1) |
Multi-User Picker | Multi-User Picker (1:1) |
Radio Buttons | Radio Buttons (1:1) |
Multi-Select | Multi-Select (1:1) |
Long Text (Text Area) | Long Text (1:1) |
Prerequisites:
Projects should have the atlassian-addons-project-access role in the permission scheme for Browse Project and Edit Issues.
Step-by-Step Guide to Merging Custom Fields (Example):
We will demonstrate the merging process using an example where we have two Select List custom fields:
"Fruits" (current field used across projects)
"Fruits (migrated)" (a redundant field that we want to merge into "Fruits")
Summary of the Merge Process:
During the merge, we will:
Check and update screen configurations, ensuring the destination field "Fruits" is present in all screens where "Fruits (migrated)" was used.
Check and update context configurations, adding values from the source field to the destination field to maintain consistency.
Check and update filters, replacing values from the source field to the destination field to maintain boards and dashboards.
Move values from the source field ("Fruits (migrated)") to the destination field ("Fruits") across all affected issues.
⚠ Warning: Jira does not provide a REST API for managing field layout, so in some cases, manual adjustments may be required after the merge.
"Fruits" (current field used across projects)
"Fruits (migrated)" (a redundant field that we want to merge into "Fruits")
(Optional) Before and after merging, use JQL to check the number of tickets affected. Ensure you have the necessary Jira permissions to view all tickets.
"Fruits (migrated)" is not EMPTY and "Fruits" is EMPTYGo to Custom Fields Report
Navigate to Doctor Pro for Jira > Reports > Custom Fields Report.
Generate a new report if needed.
Select Merging Mode
Choose the Merging mode to begin the consolidation process.
Select Source and Destination Custom Fields
Source Field: "Fruits (migrated)" (this field will be removed)
Destination Field: "Fruits" (data from the source field will be transferred here)
Since both are Select List fields, they are eligible for merging.
Review Changes & Execute Task
Confirm the changes and execute the merge.
Monitor the Task in Task Manager
Go to Task Manager and wait for the process to complete.
Jira may experience slowdowns due to issue reindexing—allow 10-15 minutes for the indexing process.
Validate Changes Using JQL (Optional)
Use JQL to confirm that all tickets previously containing "Fruits (migrated)" now have values in "Fruits".
By following these steps, you can efficiently merge duplicate custom fields, ensuring a more organized and optimized Jira instance.