Summary

Jira allows Admins to rename a Custom Field, though it won't update all references to it.

After renaming a Custom Field, Admins may find several Filters, Gadgets, Dashboards and Boards to have broken because they make a reference to 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 it's references.

Environment

Any on-prem version (Data Center and Server) of Jira Software or Jira Service Management.

Solution

Below you'll find:

1. How to find references to the Custom Field
2. How to update the references
3. Scenarios out of 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

Before you start

Stop Jira and perform a complete database backup in case you need to roll back.

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:

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%');

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%');

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%');

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

The advised approach is to manually update each referencing entity one by one through Jira's UI.

The DB updates below should only be used if the above isn't possible — and still need to be tested in a lower environment prior to Production.

Also be mindful that there may be several false-positives due to the Custom Field name matching. The 4th line on each of the update commands below match the Id of the records for precaution.

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

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 (...);

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 (...);

update "AO_60DB71_CARDCOLOR"
set "VAL" = replace("VAL", 'OLD_NAME', 'NEW_NAME')
where lower("VAL") like lower('%OLD_NAME%')
and "ID" in (...);

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

There are many 3rd party Apps that may reference Custom Fields by name and require updates similar to the ones above.

Admins should reach out to each App vendors for guidance on how to find the references and update them.

If there are script-enabling apps, Custom Fields may have also been hard-coded into the scripts by Admins and should be updated, too (probably manually).

If you learn of any other entity or places that have required updates in your instance after renaming a Custom Field, please let us know through the Feedback button below so we can improve this article!