Documentation for JIRA 4.3. Documentation for other versions of JIRA is available too.

Skip to end of metadata
Go to start of metadata

On this page:

Custom Fields Overview

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.

Custom Field Types

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 Development Hub.

Search Templates

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.

Custom Field Context

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.

Adding a Custom Field

To create a new field, associate it with a context, and add it to a screen:

  1. Log in as a user with the 'JIRA Administrators ' global permission .
  2. Bring up the administration page by clicking either the ' Administration ' link on the top bar or the title of the Administration box on the dashboard:
  3. On the menu bar on the left, under 'Issue Fields', click the 'Custom Fields' link, then click the 'Add Custom Field' link on the presented page. The 'Add Custom Field - Step 1' screen will display:
  4. Select the appropriate 'Field Type' field the list.
  5. Click the 'Next' button. The 'Add Custom Field - Step 2' screen will display:
  6. Fill in the 'Field Name' and 'Field Description'. The Field Name will appear as the custom field's title in both entering and retrieving information on issues. The Field Description is displayed beneath the data entry field when entering new issues and editing existing issues, but not when browsing issues.
  7. Select an appropriate 'Search Template' (see above). Pre-configured search templates are available for each shipped custom field type. A description of each search template will appear next to the select list when you select one.
  8. Select one or any number of 'Issue Types' to which this custom field will be available. Alternatively, select 'Any issue type' to make the custom field available to all Issue Types. You can change this in the future if you need to.
  9. Select the applicable context, that is, the 'Project(s)' to which the custom field will be available. Alternatively, select 'Global context' to make the custom field available to all projects.
    • If issue types were chosen, the custom field will only appear for those issue types for the selected project(s).
  10. Click the 'Finish' button.
  11. This will bring you to the screen association page:
  12. Select a screen, or screen tab, on which to display your newly created custom field. You must associate a field with a screen before it will be displayed. New fields will be added to the end of a tab.
  13. Click the 'Update' button. You will return you to the View Custom Fields page, which displays a summary of all custom fields in your JIRA system. You can edit, delete or configure custom fields here. This page is also directly accessible from the menu bar to the left of all Administration pages. For details please see Configuring a Custom Field.

Next Steps

Once you have created your new custom field, you can configure its:

  • default value
  • options (for custom fields of type Select List, Multi Select or Cascading Select)
  • context (see above)

For details, see Configuring a Custom Field.

Additional Resources

  • Adding a custom field tutorial video — Watch this short tutorial video to see how to add and configure a new custom field. Please note the JIRA version and JIRA edition of the tutorial video before watching.