Configuring a custom field

On this page

Still need help?

The Atlassian Community is here for you.

Ask the community

You can modify each of the custom fields in your JIRA system by changing the following:

  • Name — the label that appears to the left of the custom field when it is displayed to a user. 
  • Description — the Help text that appears below the custom field when it is displayed in the Simple Search column.
  • Search template — the mechanism for making a custom field searchable.
  • Default value — the default value of the custom field when it is first displayed to a user.
  • Options (for select and multi-select fields only) — the values from which a user can choose. See below.
  • User filtering (for User Picker fields only) — the set of users from which a user can choose. See below.
  • Context — the combination of project(s) and issue type(s) for which a given Default Value and Options will apply. See below.
    (tick) You can create multiple contexts, allowing you to specify different Default Values and Options for different combinations of projects and/or issue types.
  • Screens — the screen(s) on which the custom field will appear when an issue is created, edited or transitioned through workflow. See below (also see Defining a screen).
  • Renderers(for certain types of fields only) — see Configuring renderers and Specifying field behavior.
  • Hide/Show — see Specifying field behavior.
  • Required/Optional — see Specifying field behavior.

(warning) Note: For all of the following procedures, you must be logged in as a user with the JIRA Administrators global permission.

On this page:

Viewing custom fields

  1. Choose > Issues
  2. Select Fields > Custom Fields to open the Custom Fields page.

Editing a custom field

Editing a custom field allows you to change its name (label), description (Help text) and search template.

  1. Navigate to the Custom Fields page, locate the desired custom field and choose cog icon > Edit:
    • The Name is the label that appears to the left of the custom field when it is displayed to a user.
    • The Description is the Help text that appears below the custom field when it is displayed.

    • 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 using this procedure.

  2. Modify the fields as desired and click Update.

Configuring a custom field

The custom field context (also known as custom field configuration scheme) is not related to the field configuration scheme, and specifies the following for the custom field:

  • Default value
  • Options
  • The issue types and projects to which the default values and options apply

You can create multiple contexts if you need to associate different default values and options with particular projects or issue types.

Each custom field has a context named Default Configuration Scheme for ..., which is created automatically when you add your custom field.

Context

  1. Navigate to the Custom Fields page, locate the desired custom field and choose cog icon > Configure.
  2. Locate the context named Default Configuration Scheme for ... and click the Edit Configuration link.
  3. Under Choose applicable issue types, select the issue type(s) to which you want the default value and options to apply. You can select any issue types if you wish.
  4. Under Choose applicable contexts, select the project(s) to which you want the default value and options to apply. Note that this will apply to only issues with the selected issue type(s) as above.

Adding a new context

Adding a new context allows you to configure a custom field differently for different combinations of issue types and projects.

  1. Navigate to the Custom Fields page, locate the desired custom field and choose cog icon > Configure.
  2. Click the Add new context link. The 'Add configuration scheme context' page will be displayed (see below).
    • Under 'Add configuration scheme context', enter a 'Label' and 'Description' for your new context — these are used for administrative purposes only and will not be shown to your end-users.
    • Under 'Choose applicable issue types', select the issue type(s) to which you want the default value and options to apply. You can select Any issue types if you wish.
    • Under 'Choose applicable contexts', select the project(s) to which you want the default value and options to apply. Note that this will apply to only issues with the selected issue type(s) as above.

A custom field can only have one context per JIRA project. So you cannot have multiple contexts for different issue types in the same project.

Default value

  1. Navigate to the Custom Fields page, locate the desired custom field and choose cog icon > Configure.
  2. Locate the relevant context (there will usually only be one, named 'Default Configuration Scheme for ...') and click the Edit Default Value link in the right-hand column. The 'Set Custom Field Defaults' page will be displayed and will be particular to the custom field type:
    • (For a select list or multi-select list) Select the appropriate default value from the drop-down list.
      (info) To clear the default of a select field, click on the current default so it is no longer highlighted and then save, as described here: Unable to De-select Default Value for Multi Select Custom Field.
    • (For a cascading select list) Select the appropriate default values from the drop-down lists (one for each level).
    • (For a date field) Specify a date, or tick the check-box to make the current date the default.
    • (For other types of fields) Type the appropriate default values from the drop-down lists (one for each level).
      (info) Certain types of custom fields may not allow for defaults to be selected and will not have the Edit Default Value link.

Options

You can specify option values for custom fields of the following types:

  • Select lists
  • Multi select lists
  • Cascading select lists
  • Radio buttons
  • Multi checkboxes

You can add, remove, re-order, sort the options alphabetically, and edit the text of an option value. You can also have HTML in an option value — be sure to use complete tag pairs, and check that the HTML will display correctly.

(info) These options are case insensitive, so when using a select or multi-select list for a notification scheme, JIRA-ADMINISTRATORS will match the jira-administrators group. This means you cannot have both a JIRA-ADMINSITRATORS and a jira-administrators option, as they have the same name.

  1. Navigate to the Custom Fields page, locate the desired custom field and choose cog icon > Configure.
  2. Locate the relevant context (there will usually only be one, named 'Default Configuration Scheme for ...'), and click the Options link in the right-hand column. The 'Edit Custom Field Options' page will be displayed (see below). Here you can:
    • Select from the Edit parent select list drop-down to choose which list to edit. (For a cascading select list only)
    • Click Sort alphabetically to automatically re-order the options alphabetically.
    • Click the arrows in the Order column, or specify a number and click the Move button, to re-order the options manually.
    • Click Edit to change the text of an option.
    • Click Disable to hide an option so that it is no longer available for selection. Options that have been used cannot be removed (to preserve data integrity), but due to changing business requirements, they may become invalid over time and so you may wish to make them unavailable for new issues.
    • Click Delete to remove an option. (This will only be possible for options that have not been used.)

User filtering

You can limit the set of users available in your user picker field. The users can be limited to users in specific groups and/or project roles.

  1. Navigate to the Custom Fields page, locate the desired custom field and choose cog icon > Configure.
  2. Click Edit User Filtering.
  3. Click Enable group or project role filtering, then specify the groups and/or roles that you want to limit the user picker to.
    The user picker will only show users that are in the groups and roles selected.
  4. Click Save.

Choosing screens

  1. Navigate to the Custom Fields page, locate the desired custom field and choose cog icon > Screens.
  2. Select the checkboxes of the screens on which you wish to display this custom field.
    (info) Note that field visibility depends on the field configuration (which is not related to the custom field configuration scheme described above). See Specifying field behavior for more information.

Translating a custom field

You can translate the name and description of any custom field that you create into another language. You can only select from the language packs that are installed in JIRA.

  1. Navigate to the Custom Fields page, locate the desired custom field, and choose cog icon >Translate.
  2. Choose the language pack that this custom field translation will belong to (e.g. French), and enter the translated strings for the Field Name and Description.

Tips for custom fields

  • Limit the number of custom fields — Be careful how many custom fields you define in JIRA. More than a thousand is a large number and may affect JIRA's performance. For more information, see Scaling Jira 6.4.  
  • Use fields for reporting — Consider what reports are needed from JIRA and only create fields that support those fields. Custom field types, such as select and multi-select are great for reporting. On the other hand, text fields are not as useful, since people don't always enter data as expected by the report's query.
  • Combine field content — If just want to make sure that someone remembers to enter some information, then consider a multi-line custom text field with a text template as a default value. You may also want to try using a "table grid" custom field which lets you enter data in a searchable table. The Atlassian Marketplace has add-ons that provide this kind of functionality. Note, the standard JIRA fields such as Description do not currently support default values (see JRA-4812).
  • Don't duplicate names — Don't create new custom fields with the same name as other existing custom fields. Always check to see whether a custom field with the same name already exists before you create it. If you do, then choosing the correct field in JQL searches can become confusing for users. Also, don't create custom fields with the same name as the standard JIRA fields. For example, having two "Status" fields is particularly confusing. 
  • Make names as generic as possible — Give custom fields non-specific names that can be reused in other places later on. For example, instead of naming a field "Marketing Objective", name the field "Objective", and provide a description in the field configuration that states the JIRA projects where that field is used.

Troubleshooting custom fields

Using the JIRA admin helper

The JIRA admin helper can help you diagnose why a custom field is not showing on your screens. This tool is only available to JIRA administrators.

  1. Navigate to the View Issue, Edit Issue or Create Issue screen where the field is not showing.
  2. If you are viewing an issue, click More Actions > Where is my field? If you are creating or editing an issue, click Configure Fields > Where is my field?
  3. Enter the name of the field.
  4. Click Submit.

Tip: You can also access the 'Where is my field?' dialog via the cog menu for each issue in the issue navigator. 

Changing the description of a custom field

Not changing the description in a field configuration means that any changes you make to a custom field's description are not seen.

JIRA allows you to define a description of a custom field, and if the field configuration descriptions are left empty then the original description text will appear when you create or edit an issue, and as help text in the Issue Navigator. However you can also define different description texts in each field configuration and this will override the original field description text.

For example if a custom field "My Field" is defined with a description of "This is my field" and no field configuration changes are made, then the displayed text will be "This is my field" as expected. If field configurations are used and a description "This is my excellent field" is set for the custom field in the field description, then the displayed text will be "This is my excellent field". 

Last modified on Dec 11, 2016

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.