logo

Custom Field Toolbox for Jira

New and important in version 4!

  • The app has been renamed to Custom Field Toolbox
  • The app page has moved: Cog -> System -> (TROUBLESHOOTING AND SUPPORT section) Custom Field Toolbox
  • In the list of fields, the "Warning" icon and the "Used" column are now the "Unused fields" audit rule. The "Unused fields" rule is now disabled for fields that were marked as "used."
  • In the list of fields, the "lost" label is now the "Lost fields" audit rule.

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.

Installation

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

Usage

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

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.
  • Projects - number of projects in which there are tasks in which this field contains a value (see below).
  • Issues - 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.
  • 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.

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 - a list of screens and their tabs that contain this field.
  • Projects - a list of projects that have issues in which this field has values stored in the database. This tab displays all projects, regardless of permission settings. Click on the project name to see a list of issues in which this field is filled. The list of projects can be downloaded in CSV format.
  • 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.
  • Webhooks - list of webhooks that use this field.

Project page

The Project page contains a list of issues where this field is filled in, as well as the value of this field stored in the database. Issues are displayed in the list regardless of access settings, so it's possible that you will see the issue but not be able to access it.

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.

Rules

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 addition, there should not be any issues in which this field would contain a value stored in the database.

Please note that there may be situations in which this rule will work for a field that is calculated and actually used. If you find a field like this, just disable the rule for it.

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.

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.

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.

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.

Empty description

Field description makes instance administration more efficient.

Field name begins with lowercase

Capitalize your field name.

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.

Troubleshooting

If you find an error in our app's operation, do the following to solve the problem most effectively:

  1. Immediately after the error occurs, open Developer Tools on the same page of your browser (on Windows, press F12; on Mac, option+command+i); switch to the "Console" tab, and see if there are any errors highlighted in red. If there are errors, make a screenshot of them, or copy the text.
  2. If you can reproduce the error, enable the DEBUG logging mode for our application and reproduce it. The log will gather more complete information about what happened, which will help us solve the problem faster. To enable DEBUG mode:
  3. Go to: Cog -> System -> (TROUBLESHOOTING AND SUPPORT section) Logging and profiling
  4. Click "Configure logging level for another package"
  5. In the window that appears, enter "systems.npe.jira.cfu" in the "Package name" field, select "TRACE" in the "Logging level" field, and click Add.

Important! After completing Step 3, switch our app's logging level to WARN. To do this:

  • Go to: Cog -> System -> (TROUBLESHOOTING AND SUPPORT section) Logging and profiling
  • In the package list, find systems.npe.jira.cfu and click WARN in this row.
  • Create a zip file containing useful information about your instance. To do this, go to: Cog -> System -> (TROUBLESHOOTING AND SUPPORT section) Support tools -> Create support zip tab The "JIRA application logs" checkbox must be checked in the list that appears; if others are also checked, it will help us solve your problem faster.
  • Create an issue in our tracker, describe your problem, and attach the files received in steps 1 and 3.