Custom fields are used globally across JIRA, so you will need to have the JIRA Administrator global permission to carry out management operations such as creation and configuration.
JIRA maintains all the custom fields in a centralized location for easy management. Perform the following steps to access the custom field management page:
- Log in as a JIRA administrator user.
- Browse to the JIRA administration console.
- Select the Issues tab and then the Custom fields option:
On the Custom Fields page, all the existing custom fields will be listed. From here, you can see the name of each custom field, their type, the context they belong to, and the screens they are displayed on.
Creating a new custom field is a multistep process, and JIRA provides a wizard to help you through it. There are two mandatory steps and an optional step when adding a new custom field. You need to first select the type of custom field, then its name, followed by options if you are adding a select list custom field type. The last, optional, step is to decide which screens to add the field onto. We will walk you through the process:
- Browse to the Custom Fields page.
- Click on the Add Custom Field button. This will bring you to step 1 of the process, where you can select the custom field type.
- Search and select the custom field type you wish to add, and click on Next. This will bring you to step 2 of the process, where you can specify the custom field's name and options:
- Enter values for the Name and Description fields. If you are creating a selection-based custom field, such as a select list, you will need to add its select options, too (you can update this list later):
- Click on the Create button. This will bring you to the last step of the process, where you can specify which screen you would like to add the field onto. This step is optional as the custom field has already been added in JIRA. You do not have to add the field onto a screen. We will discuss fields and screens in Chapter 6, Screen Management.
- Select the screens and click on Update. The following screenshot shows that the newly created field is added to Default Screen:
Once a custom field has been created, you will see it on the appropriate screen when you are creating, editing, or viewing issues.
Once a custom field has been created, you can edit its details at any time. You may already notice that there is a Configure option and an Edit option for each custom field. It can be confusing in the beginning to differentiate between the two. Configure specifies options related to the custom field context, which we will discuss in the following sections. Edit specifies options that are global across JIRA for the custom field; these include its name, description, and search templates:
- Browse to the Custom Fields page.
- Select the Edit option by clicking on the cog icon for the custom field you wish to edit from the list of custom fields.
- Change the custom field details, such as its name or search template.
- Click on the Update button to apply the changes.
When making changes to the search templates for your custom fields, it is important to note that while the change will take effect immediately, you need to perform a full system re-index in order for JIRA to return the correct search results. This is because for each search template, the underlying search data structure may be different, and JIRA will need to update its search index for the newly applied search template.
For example, if you have a custom field that did not have a searcher and you just applied a searcher to it, no results will be returned until you re-index JIRA. When you make changes to the search template, JIRA will alert you with a message that a re-index will be required, as shown in the following screenshot:
We will discuss searching and indexing in more detail in Chapter 10, Searching, Reporting, and Analysis.
You can also delete the existing custom fields, as follows:
- Browse to the Custom Fields page.
- Select the Delete option by clicking on the tools icon for the custom field you wish to delete.
- Click on the Delete button to delete the custom field.
Once deleted, you cannot get the custom field back, and you will not be able to retrieve and search the data held by those fields. If you try to create another custom field of the same type and name, it will not inherit the data from the previous custom field, as JIRA assigns unique identifiers to each of them. It is highly recommended to back up your JIRA project before you delete the field.
Now that we have seen how to create and manage custom fields, we can start looking at more advanced configuration options. Different custom field types will have different configuration options available to them. For example, while all the custom fields will have the option to specify one or more contexts, the selection list-based custom fields will also allow you to specify a list of options. We will look at each of the configuration options in the following sections.
To configure a custom field, you need to access the Configure Custom Field page, as follows:
- Browse to the Custom Fields page.
- Select the Configure option by clicking on the cog icon for the custom field you wish to configure from the list of custom fields. This will bring you to the Configure Custom Field page.
The following screenshot shows that the Department custom field has two available contexts, the default context Default Configuration Scheme, which is applied to all projects (except Help Desk), and Help Desk Configuration Scheme, which is applied only to the Help Desk project:
From time to time, you may need your custom fields to have different behaviors depending on what project the issue is in. For example, if we have a select list custom field called Department, we may want it to have a different set of options based on which project the issue is being created in, or even a different default value.
To achieve this level of customization, JIRA allows you to create multiple custom field contexts for a custom field. As we have seen already, a custom field context is a combination of issue types and projects. Therefore, in our example, we can create a context for the Task issue type and the Help Desk project and set the default department to PMO.
Creating a new custom field context is simple. All you need to do is decide the issue type and project combination that will define the context:
- Browse to the Configure Custom Field page for the custom field you wish to create a new context for.
- Click on the Add new context link. This will take you to the Add configuration scheme context page.
- Enter a name to the new custom field context in the Configuration scheme label field.
- Select the issue types for the new context under the Choose applicable issue types section.
- Select the projects for the new context under the Choose applicable context section.
- Click on the Add button to create the new custom field context.
Each project can only belong to one custom field context per custom field (global context is not counted for this). Once you select a project for context, it will not be available the next time you create a new context. For example, if you create a new context for Project A, it will not be listed as an option when you create another context for the same custom field. This is to prevent you from accidentally creating two contexts for the same project.
After a new custom field context has been created, it will not inherit any configuration values as the default context such as Default Value and Select Options from other contexts. You will need to repopulate and maintain the configuration options for each newly created context.
For custom field types, select the list, checkboxes, radio buttons, and their multi-versions. You need to configure their select options before they can become useful to the users. The select options are configured and set on a per custom field context basis. This provides the custom field with the flexibility of having different select options for different projects.
To configure the select options, you need to first select the custom field and then the context that the options will be applied to, as follows:
- Browse to the Custom Fields page.
- Click on the Configure option for the custom field you wish to configure the select options for.
- Click on the Edit Options link for the custom field context to apply the options to.
- Enter the option values in the Add New Custom Field Option section, and click on the Add button to add the value. The options will be added in the order in which they are entered into the system. You can manually move the option values up and down or click on Sort options alphabetically to let JIRA perform the sorting for you.
- Click on the Done button once you finish configuring the select options:
For most custom fields, you can set a default value so your users will not need to fill them unless they have special needs. For text-based custom fields, the default values will be displayed as text by default, when the users create or edit an issue. For selection-based custom fields, the default values will be preselected options for the users.
Just like setting selection options, default options are also set on a per custom field context basis:
- Browse to the Custom Fields page.
- Click on the Configure option for the custom field you wish to configure the select options for.
- Click on the Edit Default Value link for the custom field context to apply the default values to.
- Set the default value for the custom field.
- Click on the Set Default button to set the default value.
Setting the default value will be different for different custom field types. For text-based custom fields, you will be able to type any text string. For select-based custom fields, you will be able to select from the options you add. For picker-based custom fields such as User Picker, you will be able to select a user directly from the user base.