Renaming a Custom Field and Updating References in Jira Data Center
Platform Notice: Data Center Only - This article only applies to Atlassian apps on the Data Center platform.
Note that this KB was created for the Data Center version of the product. Data Center KBs for non-Data-Center-specific features may also work for Server versions of the product, however they have not been tested. Support for Server* products ended on February 15th 2024. If you are running a Server product, you can visit the Atlassian Server end of support announcement to review your migration options.
*Except Fisheye and Crucible
Summary
Please Note
The content on this page relates to platforms which are not supported for JIRA Applications. Consequently, Atlassian cannot guarantee providing any support for it. Please be aware that this material is provided for your information only. We expect that you will follow best practices for Change Management and will test and validate these settings in a Test/Development and Staging environment prior to rolling any changes into a Production environment.
You can rename a Custom Field in Jira, but remember that not all references will update automatically.
After renaming a Custom Field, Admins may find several Filters, Gadgets, Dashboards, and Boards broken because they reference a now-invalid Custom Field name, thus rendering the JQL invalid (as if with a syntax error).
This article shares ways to assess the impact of renaming a Custom Field and how to update its references.
Environment
Any version (Data Center and Server) of Jira Software or Jira Service Management.
Solution
Below you'll find:
How to find references to the Custom Field
How to update the references
Scenarios out of the scope of this article
1. Finding Custom Field references
For queries presented below, replace OLD_NAME for the Custom Field's old or current name and NEW_NAME accordingly.
Mostly, the references are on Filters (JQL) spread out in several places in Jira:
Filters (that are used in Gadgets, Dashboards, Boards, Roadmap Plans, Subscriptions...)
Board-specific Filters (quick filters, card colors, subqueries, swimlanes...)
Automation for Jira Filters
False-positive alarm
Be mindful that the queries below may bring more results than expected due to false-positive matches — specially if the Custom Field old/current name's a common word or part of other Field names.
Admin discretion's necessary to make sense out of which matches are relevant and which are not.
Before you start
⚠️ Stop Jira and ensure you back up your database before making changes.
1.1. Filters
Filters are the base of many features in Jira and may be the root cause for several features not working if a Custom Field's been renamed:
select f.id as "Filter Id", f.filtername as "Filter Name", f.authorname as "Filter Author", f.description as "Filter Description", f.reqcontent as "Filter JQL"
from searchrequest f
where lower(f.reqcontent) like lower('%OLD_NAME%');1.2 Board-specific Filters
Agile Boards can have Filters for some features that aren't stored in the searchrequest table:
Quick Filters
select q."ID" as "Quick Filter Id", b."NAME" as "Board Name", q."NAME" as "Quick Filter Name"
from "AO_60DB71_QUICKFILTER" q
join "AO_60DB71_RAPIDVIEW" b on b."ID" = q."RAPID_VIEW_ID"
where lower(q."LONG_QUERY") like lower('%OLD_NAME%');Subquery
select sq."ID" as "Subquery Id", b."NAME" as "Board Name", sq."LONG_QUERY" as "Sub Query JQL"
from "AO_60DB71_SUBQUERY" sq
join "AO_60DB71_RAPIDVIEW" b on b."ID" = sq."RAPID_VIEW_ID"
where lower(sq."LONG_QUERY") like lower('%OLD_NAME%');Card colors
select cc."ID" as "Card Color Id", b."NAME" as "Board Name", cc."COLOR" as "Card Color", cc."VAL" as "Card Color JQL"
from "AO_60DB71_CARDCOLOR" cc
join "AO_60DB71_RAPIDVIEW" b on b."ID" = cc."RAPID_VIEW_ID"
where lower(cc."VAL") like lower('%OLD_NAME%');Swimlanes
select s."ID" as "Swimlane Id", b."NAME" as "Board Name", s."NAME" as "Swimlane Name", s."LONG_QUERY" as "Swimlane Query"
from "AO_60DB71_SWIMLANE" s
join "AO_60DB71_RAPIDVIEW" b on b."ID" = s."RAPID_VIEW_ID"
where lower(s."LONG_QUERY") like lower('%OLD_NAME%');1.3 Automation for Jira Filters
Automation for Jira can also work with JQL Filters on the scheduled triggers and conditions:
select r."ID" as "Rule Id", r."NAME" as "Rule name", c."COMPONENT" as "Component name", c."TYPE" as "Component Type", c."VALUE" as "Component value"
from "AO_589059_RULE_CFG_COMPONENT" c
join "AO_589059_RULE_CONFIG" r on r."ID" = c."RULE_CONFIG_ID"
where (c."TYPE" like '%condition' or c."TYPE" like '%jql%')
and lower(c."VALUE") like lower('%OLD_NAME%');2. Updating Custom Field references
We recommend updating each reference manually using Jira's UI.
⚠️ If the above is not possible, you can revert to the DB updates below, but ONLY after testing in a lower environment prior to using this in production
Always back up your data before making any database modifications. If possible, test any alter, insert, update, or delete SQL commands on a staging server first.
Also, be mindful that there may be several false positives due to the Custom Field name matching. For precaution, the fourth line on each of the update commands below matches the ID of the records.
2.1 Filters
update searchrequest
set reqcontent = replace(reqcontent, 'OLD_NAME', 'NEW_NAME')
where lower(reqcontent) like lower('%OLD_NAME%')
and id in (...);2.2 Board-specific Filters
Quick filters
update "AO_60DB71_QUICKFILTER"
set "LONG_QUERY" = replace("LONG_QUERY", 'OLD_NAME', 'NEW_NAME')
where lower("LONG_QUERY") like lower('%OLD_NAME%')
and "ID" in (...);Subquery
update "AO_60DB71_SUBQUERY"
set "LONG_QUERY" = replace("LONG_QUERY", 'OLD_NAME', 'NEW_NAME')
where lower("LONG_QUERY") like lower('%OLD_NAME%')
and "ID" in (...);Card color
update "AO_60DB71_CARDCOLOR"
set "VAL" = replace("VAL", 'OLD_NAME', 'NEW_NAME')
where lower("VAL") like lower('%OLD_NAME%')
and "ID" in (...);Swimlanes
update "AO_60DB71_SWIMLANE"
set "LONG_QUERY" = replace("LONG_QUERY", 'OLD_NAME', 'NEW_NAME')
where lower("LONG_QUERY") like lower('%OLD_NAME%')
and "ID" in (..);2.3 Automation for Jira Filters
update "AO_589059_RULE_CFG_COMPONENT"
set "VALUE" = replace("VALUE", 'OLD_NAME', 'NEW_NAME')
where ("TYPE" like '%condition' or "TYPE" like '%jql%') and lower("VALUE") like lower('%OLD_NAME%')
and "ID" in (...);3. Out-of-scope scenarios
Many third-party Apps may reference Custom Fields by name and require updates similar to the ones above
Contact app vendors for guidance on updating references
When using scripts either outside of Jira or via third-party Apps, Custom Fields may have also been hard-coded into the scripts and should be updated, too (probably manually).
If you learn of any other entities or places that require updates in your instance after renaming a Custom Field, please let us know through the Feedback button below so we can improve this article!
Was this helpful?