Skip to main content

Jira custom fields governance

Objective

This article will provide you with best practices around new custom field creation, identification and cleanup of unused custom fields, and some do's and don'ts with respect to using custom fields in Jira.

Jira custom fields governance

Step 1: Understand why we need to limit custom fields

In our scaling tests, we've found that a large number of custom fields is the number one reason for performance degradation. Limiting the number of custom fields and workflows, as well as reusing schemes where possible, not only helps your Jira instance maintain satisfactory performance levels, but also makes administration less complicated.
Custom fields can be configured in a variety of ways, including setting the applicable context, field configurations, and screen schemes and including the three of them in various combinations. In the test below, all the custom fields are set to global in order to see how much of an impact the raw number of custom fields has on performance.
Jira Custom Fields Governance 1
The figure shows that:
  • The number of custom fields has a high impact on actions that request or process custom issue details — viewing, searching, creating, editing, and commenting on issues.
  • It has a lesser, but still slightly noticeable impact on actions such as viewing dashboards and browsing projects.

Step 2: Identify and clean up unused custom fields

The queries below are for example purposes and may require some additional tweaking or testing in your own specific environment. Please engage a DBA in your organization for additional assistance. Some of these queries may take a long time to run in large instances with millions of rows. Run these with caution, preferably on your testing environment first.

Custom fields which are not used
1select count(*), customfield.id, customfield.cfname, customfield.description2from customfield left join customfieldvalue on customfield.id = customfieldvalue.customfield3where customfieldvalue.stringvalue is null 4and customfieldvalue.numbervalue is null 5and customfieldvalue.textvalue is null6and customfieldvalue.datevalue is null7group by customfield.id, customfield.cfname, customfield.description;
Custom fields which have low usage
1select customfield.id, count (*)2from customfield left join customfieldvalue on customfield.id = customfieldvalue.customfield3group by customfield.id having count (*) < 54order by count (*) desc
List custom fields that have not been updated after date (YYYY-MM-DD)
1select field.id, field.cfname from customfield field where field.cfname not in (2select item.field from changeitem item3JOIN changegroup cgroup ON item.groupid=cgroup.id4where item.fieldtype='custom' and cgroup.created > 'YYYY-MM-DD'5) and customfieldtypekey not like '%com.pyxis.greenhopper%'6and customfieldtypekey not like '%com.atlassian.servicedesk%'7and customfieldtypekey not like '%com.atlassian.bonfire%'8and customfieldtypekey not like '%com.atlassian.jpo%'
User activity related to a custom field

Uses the complete custom field id. (for example, customfield_10301)

1select id, entitytype, entityid, username, to_timestamp(lastviewed/1000) as lastviewed, data from userhistoryitem 2where entityid='customfield_10301'3order by lastviewed desc;
All select-list type custom fields
1select * from customfield 2where customfieldtypekey = 'com.atlassian.jira.plugin.system.customfieldtypes:select';
All custom fields along with the options
1select cf.id, cf.customfieldtypekey, cf.cfname, cfo.sequence, cfo.customvalue from customfield cf2join customfieldoption cfo on cfo.customfield = cf.id3where customfieldtypekey = 'com.atlassian.jira.plugin.system.customfieldtypes:select'4order by cfo.id, cfo.sequence;
Filters which contain a "Custom Field Name" or custom field id "10001"
1select * from searchrequest where reqcontent like '%Field Name%' or reqcontent like '%10001%';
Workflows that reference a custom field
1select * from jiraworkflows wf where wf.descriptor like '%customfield_10301%';
Fields with a global context
1SELECT distinct(p.pkey),2cfname,3cf.id,4p.pname 5FROM CUSTOMFIELDVALUE cfv6left join JIRAISSUE ji7on cfv.ISSUE = ji.id 8right join CUSTOMFIELD cf9on cf.id = cfv.customfield10left join project p11on p.id = ji.project12WHERE cf.id in (''' + globalContextIdsCommaSeparated+ ''')13GROUP BY cf.id,cf.cfname,p.pkey, p.pname14ORDER BY cf.cfname,p.pname
Non-calculated fields with contexts & no values that do not have Screen/Workflow/Notification schemes
1SELECT2cf.id id, 3to_char(min(ji.created), 'YYYY/MM/DD'),4to_char(max(ji.updated), 'YYYY/MM/DD'),5count(distinct(ji.id))6FROM CUSTOMFIELDVALUE cfv7left join JIRAISSUE ji8on cfv.ISSUE = ji.id 9left join CUSTOMFIELD cf10on cf.id = cfv.customfield 11GROUP BY cf.id12ORDER BY cf.id
Non-calculated fields with contexts, no values, and do not have Workflow/Notification scheme, but are mapped to some screens
1SELECT2cf.id id, 3to_char(min(ji.created), 'YYYY/MM/DD'),4to_char(max(ji.updated), 'YYYY/MM/DD'),5count(distinct(ji.id))6FROM CUSTOMFIELDVALUE cfv7left join JIRAISSUE ji8on cfv.ISSUE = ji.id 9left join CUSTOMFIELD cf10on cf.id = cfv.customfield 11GROUP BY cf.id12ORDER BY cf.id
Audit custom field misuse
This can be a lengthy, manual process, but here’s a potential query to assist in extracting how custom fields are being used so you can identify when fields are being used for alternate purposes or are just being misused.
1select 2 customfield.id, 3 customfield.cfname, 4 customfield.description, 5 customfieldvalue.stringvalue,6 customfieldvalue.numbervalue,7 customfieldvalue.textvalue,8 customfieldvalue.datevalue9from customfield 10left join 11 customfieldvalue on customfield.id = customfieldvalue.customfield12where 13 customfieldvalue.stringvalue is not null or14 customfieldvalue.numbervalue is not null or15 customfieldvalue.textvalue is not null or16 customfieldvalue.datevalue is not null17group by customfield.id, customfield.cfname, customfield.description;
  • Compare custom field values for each custom field ID and note usage patterns
  • Consider enhancing the query by:
    • Joining with “jiraissue” table to also pull related issue data
    • Including a custom field ID in the “where” clause to hone in on specific custom fields of interest
  • Once custom fields and offending issues are found, engage the end user to determine the use case and devise a strategy to accommodate the user’s need
Additional resources and Marketplace apps

Step 3: Set up governance around custom fields creation and usage

Once you have identified and merged or removed unused/rarely used custom fields from an instance, it's important to establish a process for the creation of new custom fields to ensure that you don't encounter the same issues again.
A few things to keep in mind here:
Evaluate requests for new custom fields: When users request a new custom field(s), you should establish a process for vetting the necessity of the request. Meet with the users to interpret their requirements for the fields and figure out if an existing field can be repurposed or if a field is needed at all. Use custom field context to limit fields to specific projects and use different values for different projects without creating a new custom field.
Verify the purpose of new custom fields: Ensure that the information captured by each field serves a justifiable purpose. If the data is not used to work on the issue or for reporting, then you don’t need it. Track the number of custom fields being used on a quarterly basis or as frequently as is practical for your organization.
Establish and share a governance policy: Create a clear and definitive set of guidelines that establish how new objects such as custom fields, workflows, and other customizations will be added to Jira. 
Get executive backing: Share your governance policy with relevant managers and executives at your organization and enlist their support. Be ready with facts to substantiate your recommendations and show how the lack of governance affects the performance of the instance and impacts the end users.

DOs

Reuse existing fields when possible.
Make field names as generic as possible.
Give your custom fields useful descriptions, including examples of valid values.
Format custom fields consistently (for example, capitalization).
Whenever possible, keep them consistent with Jira defaults.
Be careful of trailing spaces and other non-visible characters added to custom field names. These will make using scripts harder.
Err on the side of flexibility. For example, a multi-select field is more flexible than a single-select field.
Translate custom field names for your users who are using a different language pack.
Know how and when to use custom field contexts.
Use the Where is my field? feature to track down missing fields.
Have a governance policy and make it easy for users and executives to find.
Use custom fields contexts appropriately. For example, avoid using global context when a custom field is only being in used in one project. 
Avoid setting default values for your custom fields whenever possible.
When creating custom fields with a drop-down list, try to minimize the number of options available. 

DON'Ts

Don’t create custom fields with duplicate names. This can lead to administration mistakes, reporting issues, and custom scripts chaos.
Don’t create option fields that have to be updated frequently. For example, a select list with usernames will quickly become outdated as people’s roles change.
Don’t add the option value None. This option already exists when the field is made, and adding it to the list makes reporting harder.

Conclusion

There is no easy path to reducing the number of custom fields once they are already in use. It’s a time-consuming process that requires a great deal of care to ensure that no critical data is lost. Unused and rarely used custom fields can be identified, but you must exercise care in removing them. Test the changes in a QA environment before rolling out the changes to production. Proactively creating processes around customizations in Jira can be very useful in the long run to control the growth of the instance and ensure that the system is still performant and serving the needs of its users. 

Was this content helpful?

Connect, share, or get additional help

Atlassian Community

Purpose-fit guidance and support to ensure your team's success

Each deployment of Atlassian products is unique, so we offer a breadth of services to design, implement, and optimize solutions for scale.

Learn More