Documentation for JIRA 4.4. Documentation for other versions of JIRA is available too.
To help you tailor JIRA to your organisation's needs, JIRA enables you to add custom fields in addition to the built-in fields. For example, if you needed to capture information about the database that each issue relates to, you could add a custom field called 'Database'.
You can choose the most suitable custom field type (see below) for your purposes. For example, you could choose to create this field as a Free Text Field, in which users can type whatever they wish, or as a Select List, which will force users to select from a list of pre-defined options.
Once you have created a new custom field (see below), you will need to add it to one or more screens so that it is available to users. For more information about how field and screens interrelate, please see Configuring Fields and Screens.
Custom fields are always optional fields. This means that you can create a new custom field without requiring existing issues to be changed. The existing issues will contain no value for the new custom field, even if a default value is defined.
On this page:
JIRA ships with over 20 custom field types and you can find many more in the Plugin Exchange (e.g. the JIRA Toolkit). A sample of the types are listed as follows:
Custom Field Type |
Description |
---|---|
Cascading Select |
Multiple select lists where the options for the second select list dynamically updates based on the value of the first |
Date Picker |
Input field allowing input with a date picker and enforcing valid dates |
Date Time |
A custom field that stores dates with a time component. |
Free Text Field (unlimited text) |
Multiple line text-area enabling entry of longer text strings |
Group Picker |
Choose a user group using a popup picker window. |
Labels |
Input field allowing labels to be added an issue. E.g. If you are using GreenHopper, the 'Epics' feature is implemented via a 'Labels' custom field. |
Multi Checkboxes |
Checkboxes allowing multiple values to be selected |
Multi Group Picker |
Choose one or more user groups using a popup picker window. |
Multi Select |
Select list permitting multiple values to be selected |
Multi User Picker |
Choose one or more users from the user base via a popup picker window. |
Number Field |
Input field storing and validating numeric (floating point) values |
Project Picker |
Select list displaying the projects viewable by the user in the system |
Radio Buttons |
Radio buttons ensuring only one value can be selected |
Select List |
Single select list with a configurable list of options |
Single Version Picker |
Choose a single version from available versions in the project. |
Text Field |
Basic single line input field to allow simple text input of less than 255 characters |
URL Field |
Input field that validates a valid URL |
User Picker |
Choose a user from the user base via a popup picker window. |
Version Picker |
Choose one or more versions from available versions in the project. |
To build your own custom field types, see the tutorial at the JIRA Developer Documentation.
Search Templates are responsible for indexing a custom field as well as making it searchable through the Issue Navigator (note that custom fields are not searchable via QuickSearch). Each of the default custom field types has a related preconfigured search template.
When you create a new custom field (see below) you will need to specify its Search Template.
The custom field context allows your custom field to be configured differently for numerous different combinations of issue types and projects. For example, your custom field could have different default values for different projects (and/or issue types).
When you create a new custom field (see below) you will need to either select the applicable issue type(s) and project(s), or define the custom field to be global. You can change this later if required — see Configuring a Custom Field.
To create a new field, associate it with a context, and add it to a screen:
Once you have created your new custom field, you can configure its:
For details, see Configuring a Custom Field.