Custom Field Toolbox for Jira

1. Motivation

The ability to create custom fields makes Jira a powerful tool for managing workflows and allows you to create highly adapted objects for modeling your organization's work. However, too many custom fields can seriously degrade the performance of your Jira instance. Scaling tests show that the number of custom fields plays a crucial role in Jira performance.

Custom Field Toolbox for Jira - an app for Atlassian Jira that allows you to improve the performance of your Jira instance by optimizing custom fields. In addition, the app provides advanced information about custom fields for more efficient administration and customization of your instance.

A key feature of the app is an in-depth analysis of the use of custom fields in issues, as well as in various Jira configuration objects, such as screens, workflows, saved filters, etc. This analysis allows you to delete unnecessary fields without losing important information and side effects, and thus optimize your instance's performance.

2. Installation

Install the app via the Atlassian Marketplace or follow the standard installation process through the UPM. The app doesn't have any settings, so you can start using it right away.

3. Usage

The app page is at Cog → System → (TROUBLESHOOTING AND SUPPORT section) Custom Field Toolbox

3.1 Fields Tab

The Fields tab allows you to review the use of custom fields in various Jira configuration objects, as well as get additional information about the fields themselves. The list of fields is displayed as a table with custom columns. Here is a list of all the columns (columns marked with asterisks are hidden by default):

ID*	Field identifier.
Name	Field name.
Type	Field type name.
Type Key*	Field type key.
Type Provider*	Field type provider. If the field type is provided by a third-party app, the name of that app will be shown here.
Search Template*	Search templates are responsible for indexing a custom field, as well as making it searchable via Simple Search and Advanced Search (note that custom fields are not searchable via Quick Search). Every custom field type has a preconfigured search template, but you may select a different template.
Index values	Number of issues in which this field has values stored in the search index.
DB values	Number of issues in which this field has values stored in the database. Hereinafter is a special stipulation about the database, as we consider that calculated fields do not store values and their Issues column will always be empty.
Screens	Number of screens that use this field.
Saved Filters	Number of saved filters that use this field.
Workflows	Number of workflows that use this field.
Dashboards	Number of dashboards that use this field.
Notification Schemes	Number of notification schemes that use this field.
Issue Security Schemes	Number of issue security schemes that use this field.
Permission Schemes	Number of permission schemes that use this field.
Webhooks	Number of webhooks that use this field.
Locked*	These fields are locked to prevent accidental changes that can subsequently break the operation of JIRA Software.

You can filter and sort the table by almost any column. The table can be downloaded in CSV (comma separated) format.

To open .csv files with Excel, see MS doc.

Click on the field name for more detailed information.

3.1.1 Field page

This page contains detailed information about the field and its use in your Jira configuration. Depending on the Jira configuration, the page may contain all or some of the following tabs:

Field	Basic information about the field.
Type	Information about the field type.
Configurations	Information about this field in various field configurations.
Screens	List of screens and their tabs that contain this field.
Values	A list of projects in which this field has a value in the database, or in the search index. For each project, the number of corresponding values is shown. If the number of indexed values does not match the number of values in the database, such a project is highlighted in yellow.
Saved filters	List of saved filters that use this field.
Workflows	List of workflows that use this field. Indicates in which workflow configuration objects (conditions, validators, etc) the field is used for each workflow.
Dashboards	List of dashboards and their gadgets that use this field.
Notification Schemes	List of notification schemes and events that use this field.
Issue Security Schemes	List of issue security schemes and security levels that use this field.
Permission Schemes	List of permission schemes and permissions that use this field.
Webhooks	List of webhooks that use this field.

3.2 Audit Tab

The Audit tab is where you can get tips on optimizing the configuration of your instance's custom fields. An audit is conducted according to a number of rules. Each field is checked for compliance with each rule. Each rule represents one or more criteria that a field must meet in order to satisfy this rule. The rule can be disabled completely, or for individual fields.

3.2.1 Rules

3.2.1.1 Unused fields

Unused fields can negatively affect the performance of your instance, as well as make it difficult to administer. This rule shows the following fields.

In order to comply with this rule, the field must not be used:

on any screen
in any of the saved filters
in any workflow
in any webhook
in any notification scheme
in any issue security scheme
in any permission scheme

In addition, there should not be any issues in which this field would contain a value stored in the database or in the search index.

Please note that this rule will work for a field that is calculated but not indexed. Some of these fields may actually be used. If you find a field like this, just disable the rule for it.

3.2.1.2 Lost fields

Lost fields are what remains from deleted apps. In some cases, deleting the values of these fields may improve performance.

If you delete an app that proided a custom field type, the values of this field remain in the database for issues. Performance can be negatively affected if there are too many values like this.

The Custom Field Toolbox analyzes the database; if values are found in a custom field, even if the field type is not available, it is assumed that the "lost fields" rule has been applied to this field.

3.2.1.3 Duplicate Field Names

The presence of fields with the same name significantly complicates the setup and administration of the instance, and can also lead to errors during customization.

3.2.1.4 Field description contains HTML/JS

It is strongly not recomended to use HTML/JS customizations in custom field descriptions. It's hard to maintain, harder to get right and generally the wrong solution. If you insist on doing it, then building your own add-on is the only real way to do it.

3.2.1.5 Field name contains leading/trailing spaces

Leading or trailing spaces of the field name can make it difficult to customize if there is a need to refer to the field by name.

3.2.1.6 Empty description

Field description makes instance administration more efficient.

3.2.1.7 Field name begins with lowercase

Capitalize your field name.

3.3 Field Types tab

The Field Types tab contains a list of available field types in your instance. When you create a new field, you are prompted to select the field type from this list. Each type has a name, key, description, provider, category, and access. A field provider is an app that provides functionality for this field type. Apps can be supplied by third-party developers, or they can be embedded in Jira, depending on the package (Core/Software/Service Desk/Ops). For example, the Custom Field Types & Searchers provider is in all packages, while the JIRA Agile provider is only in Jira Software.

If the Field Type is provided by a third-party app, it will not be available when the app is deleted.

3.4. Data caching

The data for the field table and for the Audit tab is generated during the instance scan. After the scan is completed, this data is cached, so you do not need to run the scan every time you open the field table or the Audit tab.

When you are on a page with cached data, you see an information icon and a data refresh button in the upper right corner. When you hover over the icon, a tooltip appears containing the age of the cache. As the cache ages, the icon changes color: it turns yellow 8 hours after the last update, and red after 20 hours.

After 24 hours, the cache is automatically reset, or you can reset it manually at any time by clicking on the refresh button.

The cache is global. That is, if one user launched a scan and thereby updated the cache, then all other users will see the data from this cache. If one user resets the cache, then it resets for everyone else.

4. Troubleshooting

See our Troubleshooting guide.