Jira comes equipped with many useful standard fields, designed to capture essential business data. However, it also lets you add custom fields in addition to the built-in fields to fit your business’s specific needs.
While this allows for a great deal of flexibility, it is essential to carefully manage your custom fields: it’ll make your administration easier as having too many custom fields may affect Jira’s performance but also your work as a Jira admin.
Below, you’ll find essential resources, how-tos, and expert advice to help you adjust the way you manage custom fields in Jira so you capture the right data for your business, while ensuring your configuration is sustainable in the long run.
Keep on reading to understand Jira custom fields, or jump ahead to the section that interests you most.
- Essentials things to know about custom fields in Jira
- Do’s and Don’ts for managing custom fields in Jira
- Optimizing Jira custom fields: a step by step process
- Governance: best practices to handle Jira custom fields requests
Essentials things to know about custom fields in Jira
What are Jira custom fields and how do they work?
Custom fields complement the built-in fields in Jira by allowing you to track information specific to your team’s needs inside Jira issues. You can create custom fields to capture virtually anything and choose to display any number of custom fields when creating, editing, viewing or transitioning Jira issues.
They also act as filters for Jira issues, when performing issue search, in reports or dashboard gadgets, so users can know better where their work stand at a glance.
The anatomy of a Jira custom field
When talking about custom fields, there’s more than meets the eye. Jira custom fields each have a number of attributes that will define what data they can contain, and how this data will be presented, and searched for instance. Here’s the list of attributes1 you’ll be manipulating when creating, editing or deleting custom fields.
- Name: the label that appears to the left of the custom field when it is displayed to a user on a screen.
- Description: the help text that appears next to the custom field on hover.
- Default value: the default value of the custom field when it is first prompted to a user.
- Context (also known as custom field configuration scheme): the combination of project(s) and issue type(s) for which a given default value and a set of options will apply.
As we’ll discuss later in this guide, you can and often should create multiple contexts for a given custom field, allowing you to associate different default values and options with particular projects or issue types. This can help limit the number of custom fields by reusing them in a different way across your Jira instance. - Screens: the screens on which the custom field will appear when an issue is created, edited or when it is transitioned through its workflow. A screen also allows you to split subsets of fields across multiple tabs.
- Search template: the mechanism for making a custom field searchable via Basic Search and Advanced Search, also responsible for the indexing of custom fields.
- Options: the values from which users can choose . These values can be manually entered by a Jira admin or live fetched from an external datasource using an app.
Options are only available for select lists, multi select lists, radio buttons, multi checkboxes and cascading select lists. - User filtering: the set of users which the end-user can pick from in a User Picker Field. These options can be limited to users in specific groups and/or project roles.
Additionally, when defining field behavior for certain project(s) and issue type(s) combinations using field configurations, you’ll be able to configure:
- Hide/Show: whether the field is visible on the view or hidden
- Required/Optional: whether the field must be filled or is optional
- Renderers: renderers defines how a field’s value is going to be displayed, they affect the view, not the data itself.
Jira custom fields and reporting
Custom fields are a great way to add rich data to your issues, and they’re extremely useful data points to get insights from in reports, search queries or on dashboards.
However, not every custom field type is built equal when it comes to reporting. Structured custom fields such as select and multi select lists are particularly effective, as the user has a limited number of options to choose from, and thus there’s a known fixed set of options to search from and display in your reports. On the other hand, text fields are less structured and can only be searched using the contain (~) operator, meaning they’re a lot less useful in reporting as people don’t always enter data correctly or as expected by the JQL query used in the report.
Cloud only: custom fields in Next-gen projects
If you’re using Jira on Cloud, you have the option to empower your users to create Next-gen projects. Next-gen project allow users to create and set-up their own issue types and custom fields, basically to configure their project to match their team’s specific needs without relying on a global Jira admin. These projects are self-contained, meaning fields created in next-gen projects can’t be used by other projects which should prevent them to affect performance globally. Similarly you can’t use a custom field created in a classic project on your next-gen project issues.
While this “DIY” approach offers some benefits in terms of flexibility, you should think twice about going down that road, especially if you need cross-project reporting that requires shared custom fields. Before teams create Next-gen projects, make sure they can clearly define the business value of having a self contained project with custom fields that can’t be shared with other projects as there is no easy turning back.
If you wish to explore this new paradigm to project management in Jira, consider starting with a small number of power users that you will train (by default, anyone can create a next-gen project, so make sure you set up the appropriate permissions). You can share this best practice guide about custom fields with them as a reference.
Apps and custom fields
Apps are additional bricks Jira admins can add to their instance, allowing them to customize the tool to their company’s specific needs and enhance it with further functionality. There are two ways apps can leverage custom fields: first to store additional data related to the app functionality in Jira, and second to reuse the data stored in the fields that are already available on the instance as an input. How custom fields are used depends on the app functionalities. For instance an app such as Tempo Planner will leverage data stored in fields to display a plan while an app such as Elements Connect will provide custom fields that fetch their values from external data sources.
While the custom fields types provided by Jira are already extensive, you might want to consider using an app to enhance its capabilities when in need of calculated fields (as Jira can’t natively provide with any kind of computation in custom fields) or when the information the field will capture already exist in one of your external referential and you’d rather fetch it from there.
One important thing to note is that when an app is deactivated or uninstalled, their custom fields remain in the Jira database even if they are removed from screens and the custom fields section of the Jira admin.
Do’s and Don’ts for managing custom fields in Jira
What are the considerations for creating custom fields in Jira? Here’s our curated list of do’s and don’ts for effectively managing your Jira custom fields, and avoiding custom fields bloat.
DO’s
- Be careful how many custom fields you define in Jira
Every custom field has a cost in terms of performance for the instance, but also in terms of time of complexity to fill in requests for users. Strive to challenge the necessity of each custom field early on, this will save you from having to run a custom fields audit because of poor performance later on. - Make custom fields names generic
Try to give custom fields non-specific names that allow you to reuse them in other places. Use context to define project / issue type specific options, if needed. For example, name your field “Rating” instead of “Support Rating” . - Translate custom fields names
If you have users using different language packs, make sure you translate your custom fields accordingly. This will ensure your custom fields are understood correctly. - Use custom fields contexts judiciously
Restrict the custom fields context where appropriate, and avoid using global context when it’s not necessary. This will help optimize your Jira instance performance. - Automatically fill in Jira fields when possible
As a Jira admin, your job is to strive for simplifying issue creation for users while maintaining a high-level of data accuracy and enough information in the Jira issue for it to be effectively handled. If you already have the information you’re requesting from users stored in an other system, consider using an app to retrieve data from external datasources, automatically fill fields or guide users with select lists that fetch their values from your external sources.
DON’Ts
- Don’t duplicate names
Do not create new custom fields that have the same name as other existing fields …or search in JQL will become a nightmare for users. This can also lead to administration mistakes and custom script errors. Always run a check to see no other field in the instance share the name of the field you’re about to create. - Don’t create option fields that have to be manually updated frequently
Avoid creating option fields if the options provided are likely to frequently become outdated and require a manual update as data is likely to become inaccurate. However, if the list of options you want to provide is being maintained in an other system (your CRM, an Asset Manager…), an app that can fetch this data and display it in Jira can spare you the maintenance of the list options in Jira and provide an efficient solution. - Don’t abuse the required attribute
While there’s a strong temptation to make fields required, you should use this option sparingly as it makes creating tickets more difficult. If a custom field must be required, always have a way for the user to say “I don’t know”, otherwise you might end up with erroneous data.
Optimizing Jira custom fields: a step by step process
When too many custom fields affect your Jira instance performance
Research has shown that having too many custom fields can have a dramatic impact on your Jira instance performance, as the response time of any action that involves custom fields is affected by the raw number of these objects available in Jira.
As show below, the difference in response time per action for an instance with 1400 custom fields and one with 2800 is affected the most for Search with JQL, and Create issue, two commonly performed actions.
If you’re experiencing slow load time on your Jira instance, optimizing custom fields can lead to significant improvement in the quality of service you deliver to your users. Here’s a high-level step-by-step process on how to approach this project.
1. Audit your Jira custom fields
First, you need to get a clear list of the fields that are currently implemented in your instance. There are a few way to identify them: you can do a manual examination, use an app from the Marketplace such as Cleaner for Jira or Custom Fields Usage for Jira (Server only) or Jira’s built-in Custom Fields Optimizer (Data Center only).
Once you’ve established the list of custom fields available in your instance, it’s time to classify them and assess whether they’re still needed or not.
Process step by step in your investigation: identify how they were created (by Jira, by an app, or by an admin). For the ones that were created by an admin, check for duplicates or fields that have too narrow names, determine the fields’ scope and current use in projects, screens, workflows and users’ JQL queries. Also question the business value of the custom fields.
Once you’re done reporting this information in your spreadsheet, you’ll be ready to move on to the next step: deciding on how to optimize your Jira custom fields.
2. Decide what to do with your custom fields
Now that you’ve assembled all the necessary information about your Jira custom fields, it’s time to decide what to do with them. For each custom field, you have six options:
- Keep it as is
- Rename it for the sake of clarity and re-usability
- Delete it purely and simply
⚠️ Bear in mind that this operation can’t be undone, and the values in the database will be deleted. - Hide it from the screens while preserving the data
- Limit its scope to specific projects context
- Merge it with other custom fields that are essentially the same
3. Prepare stakeholders for the changes
Loss aversion is a very common fear. When working on optimizing your custom fields list, always make sure to explain to users and project admins why you’re doing this, and that in doing so you will not take away the functionality from them but rather find a more elegant way to provide them with this functionality.
Make sure also to state that you’ll only delete fields that aren’t used anymore, and with the agreement of the project admins of projects previously using that field. Be prepared to share data that shows how the field isn’t valuable anymore.
4. Advice for the actual implementation
Always ensure that your changes are tested in a test environment before rolling them out to production, and allow enough time to these tests. This may seem like an overkill sometimes, but be careful so that no data that’s critical to a team is lost in the process.
Governance: best practices to handle custom fields request
As the saying goes, an ounce of prevention is worth a pound of cure. Whether you’ve had to go through an audit and field clean up, or are just getting started with custom fields, here are some tips around custom fields requests management that will help you keep your Jira instance clean and performing well.
Pieces of information to collect for each new field request
While you can provide your users with a request form for new fields directly in your Jira support project, you’ll want to spend some time with the project lead or user that brought you this request to interpret their requirements for the new field, understand the underlying business needs and determine how to translate these requirements in your Jira instance and whether a new field is indeed needed or not.
For each new field request, try to get the most context you can. By the end of your investigation, you should know:
- the desired field name
- the purpose of the field
- the type of data that will be collected ( text, number, date, checkbox, select list…)
Pay special attention to interpreting the user’s requirement around the field type correctly, as once a field is created with a certain type it can not be changed later. Asking the requester for examples of the data the field will contain can help prevent such errors. - how and when in the issue lifecycle the data will be collected (manually entered or synced from an external referential)
- the screens on which the field should be shown
- for select lists and checkboxes, the list of options the user can choose from
- the validation rules for the field
A checklist for evaluating requests for new custom fields
Just because you can, doesn’t mean you should. By carefully assessing the requests you get from users you’ll truly be in a position to make the best choices for your Jira instance.
Take a moment to assess whether or not a new custom field is legitimately needed by reflecting on the following aspects:
- What would be the business value of the new field?
Always verify there’s a clear purpose for capturing a piece of information in a new field by asking the requester: how will knowing this information impact how you do your job? How is the data needed to perform your work or for reporting? It may sound obvious, but more often than you think you’ll find out the need isn’t clear. - Does the data need to be structured?
Ask the requester: will you search or filter issues based on this field’s value? will you need to run reports based on the values of this field?
If not, consider simply specifying what’s needed from the end user in the hint of the description field on the issue creation screen. - Will the new field be used by multiple teams across the organization?
Seeking for mutualization of custom fields across your Jira instance is a very effective way to fight custom field proliferation. Some companies even have a requirement that at least two teams benefit from the new field for it to be created. - Is there already a built-in Jira field or an other custom field that could fit this purpose?
Jira comes with a lot of built-in fields, and you probably have already added custom fields to fulfill previous requests on top of that. Before moving further with a new custom field creation consider reusing an existing field with a new context for instance. - How long will it take a user to reliably collect and submit the information?
For fields to be useful, they need to be filled correctly with accurate information. Remember that every field has a cost: no one likes to fill-in endless forms. Where possible consider automatically populating dropdown list options or read-only fields with data from your external databases or Cloud apps. This will save your end-users time while at the same time ensuring the accuracy of the data in Jira.
Once you’ve answered these questions, making the call for whether or not to create a custom field should be a straightforward decision.
Make managing custom fields requests a part of your Jira governance processes
Each company has its own way of governing its processes – yet there are some common best practices that can help you ensure your Jira instance keeps running smoothly and rules about its customization are well understood. Consider having a governance policy around custom fields and make it easy for users managers and executives to find. You’ll want the rules for how new objects such as custom fields, workflows, etc get added to Jira to be clear and unambiguous for everyone.
A Jira Advisory Board made up of different profiles (executive, project lead, end user…) is also a good way to make sure decisions are taken based on the collective insights of different stakeholders and with a global perspective, ultimately leading to more trust and efficiency in the way the solution is administered.
Maintain and Sustain
Ensuring the performance and optimal configuration of your Jira instance is not a one time job. We recommend you regularly audit your custom fields and make sure that you and other Jira administrators at your company are following the quality standards and procedures that you’ve put in place to ensure custom fields are managed the right way at your company.
Make your Jira instance sustainable for future generations to come. There will be a day when you will leave, and you should leave with pride that you have built a maintainable and sustainable environment that has helped your company grow the right way.
References
1. Configuring a custom field, Atlassian Documentation
2. Performance testing for custom fields, using the methodology detailed in their Performance and Scale testing report for Jira Data Center, Atlassian Documentation