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

Skip to end of metadata
Go to start of metadata

What is a 'Field Configuration'?

A Field Configuration is a set of definitions for all fields, including both standard fields and custom fields.

A Field Configuration allows you to specify field behaviour. For each field, a Field Configuration specifies:

  • the description that appears under the field when an issue is edited
  • whether the field is hidden or visible
  • whether the field is required (i.e. the field will be validated to ensure it has been given a value) or optional
  • (for text fields only) which renderer to use

You can create multiple Field Configurations (see below). You can then associate different Field Configurations with different issue types by creating a Field Configuration Scheme. Once created, a Field Configuration Scheme can be associated with one or more projects, allowing you to control field behaviour on a per project, per issue type basis.

For more information, please see the Overview Diagram.

Editing a Field Configuration

To change the behaviour of fields:

  1. Log in as a user with the 'JIRA Administrators' global permission.
  2. Select 'Administration' > 'Issues' > 'Fields' > 'Field Configurations' (tab) to open the 'View Field Configurations' page.
    (tick) Keyboard shortcut: 'g' + 'g' + start typing 'field configurations'
  3. Locate the Field Configuration of interest and click the 'Configure' link to open the 'View Field Configuration' page (below), which lists all system and custom fields in a table.
    (info) The 'Edit' link only allows you to change the Name and Description of the Field Configuration, not of individual fields. Also note that the 'Edit' link is not available for the 'Default Field Configuration'.
  4. In the 'Operations' column, you can perform the following actions for any field:
    • Edit — change the field's description (i.e. help text).
    • Hide/Show — hide the field from view or show it.
    • Require/Optional — set a field to be required (so that whenever a field is edited it must be given a value) or optional.
    • Renderers — change a field's renderer (see Configuring Renderers for more information).
      Screenshot 1: The 'View Field Configuration' screen

Editing a Field's Description

Fields can be given descriptions to better identify the meaning of the field. These descriptions are usually displayed under the field on the creation of an issue and whenever it is edited, e.g.:

Screenshot 2: Sample description text shown beneath the 'Assignee' field

To edit the description of a field:

  1. Log in as a user with the 'JIRA Administrators' global permission.
  2. Select 'Administration' > 'Issues' > 'Fields' > 'Field Configurations' (tab) to open the 'View Field Configurations' page.
    (tick) Keyboard shortcut: 'g' + 'g' + start typing 'field configurations'
  3. Locate the Field Configuration of interest and click the 'Configure' link to open the 'View Field Configuration' page ([above|#View_Field_Configuration).
  4. Click the 'Edit' link next to the field you want to change to open the 'Edit Field Description' page.
  5. Update the field's description and then click the 'Update' button.

Hiding or Showing a Field

If your organisation or project has no use for a particular field, you have the option to hide it. Hiding a field will ensure that the the field does not appear on any Screens (i.e. issue operation Screens, workflow transition Screens) where the Field Configuration applies.

(info) Please note:

  • Hiding a field in the Field Configuration is distinct from not adding a field to a Screen. Fields hidden through the Field Configuration will be hidden in all applicable Screens, regardless of whether or not they have been added to the Screen.
  • For fields that have a default value: If the field is hidden in the Field Configuration, then it will not receive a value when an issue is created, regardless of whether the field is present on the 'Create Issue' screen(s). (The following fields can have a default value: 'Resolution'; 'Status'; 'Priority'; 'Issue Type'; custom fields.)
  • The fields 'Summary' and 'Issue Type' cannot be hidden and as such there is no 'Hide' option available for these fields.
  • If you hide the 'Fix For Version' field, the Change Log and Road Map reports will not work.

To hide a field:

  1. Log in as a user with the 'JIRA Administrators' global permission.
  2. Select 'Administration' > 'Issues' > 'Fields' > 'Field Configurations' (tab) to open the 'View Field Configurations' page.
    (tick) Keyboard shortcut: 'g' + 'g' + start typing 'field configurations'
  3. Locate the Field Configuration of interest and click the 'Configure' link to open the 'View Field Configuration' page ([above|#View_Field_Configuration).
  4. Click the 'Hide' link next to the field you no longer want. The field will then fade grey to signify that it has been hidden.
    (info) You can make this field visible again at any time by clicking the 'Show' link.

Making a Field Required or Optional

Certain fields within your organisation may be compulsory for issues. In this case you can set a field to be required, so that JIRA validates that the field has been given a value whenever an issue is edited. If a required field has not been given a value, JIRA will return an error informing the user that the field should be filled, e.g.:

Screenshot 3: Sample validation of the 'Fix Version' field

To make a field required:

  1. Log in as a user with the 'JIRA Administrators' global permission.
  2. Select 'Administration' > 'Issues' > 'Fields' > 'Field Configurations' (tab) to open the 'View Field Configurations' page.
    (tick) Keyboard shortcut: 'g' + 'g' + start typing 'field configurations'
  3. Locate the Field Configuration of interest and click the 'Configure' link to open the 'View Field Configuration' page ([above|#View_Field_Configuration).
  4. Click the 'Required' link next to the appropriate field. The text "Required" will appear next to the field.
  5. You can make the field optional again by clicking the 'Optional' link.

(info) Please note:

  • Fields that are hidden cannot be set to required. Making a hidden field required will make it "visible" as well.
    *If you set a field to "required", ensure that the field is present on your 'Create Issue' screen(s). Note that you can have different field configurations for different projects and issue types (see 'Associating field behaviour with Issue Types'); so you need to ensure that all "required" fields are present on the 'Create Issue' screens for all associated projects and issue types (see 'Associating screens with Projects and Issue Types'). There is a feature request at JRA-5783 to make a field required only on one transition. Please watch it for status updates.

Changing a Field's Renderer

JIRA renderers affect the display of a field's content, enabling you to choose a style which best suits your organisation and your users.

JIRA currently ships with the following renderers:

  • for text fields:
    • the Default Text Renderer, which displays plain text; and
    • the Wiki Style Renderer (utilising the Confluence wiki engine), which displays rich text (HTML).
      (info) To see how a 'Wiki Style Renderer' field will look when it is displayed to a user, please see Editing Rich-Text Fields.
  • for multi-select fields:
    • the Autocomplete Renderer, which allows the user to start typing text which is then 'autocompleted', or to select from a drop-down list of options; and
    • the Select List Renderer, which simply provides a drop-down list of options.
      (please note: for custom fields of type "Multi Select", only the Select List Renderer is available)

Before you change the renderer for a specific field, please read 'Configuring Renderers', paying particular attention to the section 'Implications for JIRA operations'.

To change the renderer for a specific field:

  1. Log in as a user with the 'JIRA Administrators' global permission.
  2. Select 'Administration' > 'Issues' > 'Fields' > 'Field Configurations' (tab) to open the 'View Field Configurations' page.
    (tick) Keyboard shortcut: 'g' + 'g' + start typing 'field configurations'
  3. Locate the Field Configuration of interest and click the 'Configure' link to open the 'View Field Configuration' page ([above|#View_Field_Configuration). The 'Name' column indicates which renderers are currently enabled for all renderable fields, with the current renderer shown in brackets immediately below its field name.
  4. Click the 'Renderers' link for the field you want to change. This will take you to a page where you will have the option to select a renderer from all configured and available renderers:
    Screenshot 4: choosing a renderer for the 'Comment' field
  5. As shown above, this page will warn you if there are issues that will be affected by the change. If no issues will be affected then the warning does not show. From this page, choose the renderer you wish to use and click 'Update'. You will be presented with a confirmation page:
    Screenshot 5: confirming a renderer for the 'Comment' field

Changing the renderer only affects the display of the issue data that exists in the system. You can therefore toggle back and forth between renderer types safely.

Managing Multiple Field Configurations

You can create multiple field configurations for use on separate projects and issue types.

About the 'Default Field Configuration'

When JIRA is installed, the 'Default Field Configuration' is created automatically. All new projects are associated with this configuration. This configuration is also used for projects that are not associated with a Field Configuration Scheme.

Note that it is not possible to delete the Default Field Configuration.

Adding a Field Configuration

  1. Log in as a user with the 'JIRA Administrators' global permission.
  2. Select 'Administration' > 'Issues' > 'Fields' > 'Field Configurations' (tab) to open the 'View Field Configurations' page, which lists all your field configurations:
    (tick) Keyboard shortcut: 'g' + 'g' + start typing 'field configurations'
    Screenshot 6: the 'View Field Configurations' page
  3. The 'Add' new field configuration form is located at the bottom of the 'View Field Configurations' page. Enter the name of the new configuration on this form and optionally add a description.

Note that a newly created Field Configuration will not take effect until it has been activated (see below).

Editing a Field Configuration

  1. Log in as a user with the 'JIRA Administrators' global permission.
  2. Select 'Administration' > 'Issues' > 'Fields' > 'Field Configurations' (tab) to open the 'View Field Configurations' page (above).
    (tick) Keyboard shortcut: 'g' + 'g' + start typing 'field configurations'
  3. Click the 'Edit' link next to the field configuration you wish to edit. The 'Edit Field Configuration' page opens, which allows you to edit the field configuration's name and description.

Deleting a Field Configuration

  1. Log in as a user with the 'JIRA Administrators' global permission.
  2. Select 'Administration' > 'Issues' > 'Fields' > 'Field Configurations' (tab) to open the 'View Field Configurations' page (above).
    (tick) Keyboard shortcut: 'g' + 'g' + start typing 'field configurations'
  3. Click the 'Delete' link next to the field configuration you wish to delete.
    (info) You will be prompted to confirm this operation.

(info) Please note:

  • The Default Field Configuration cannot be deleted.
  • You can only delete a field configuration that is not associated with a Field Configuration Scheme.

Copying a Field Configuration

  1. Log in as a user with the 'JIRA Administrators' global permission.
  2. Select 'Administration' > 'Issues' > 'Fields' > 'Field Configurations' (tab) to open the 'View Field Configurations' page (above).
    (tick) Keyboard shortcut: 'g' + 'g' + start typing 'field configurations'
  3. Click the 'Copy' link next to the field configuration you wish to copy.
  4. Enter the name and description of the new field configuration
  5. Click the 'Copy' button. You will now be directed back the 'View Field Configuration' page and your copied field configuration added to the list.
    (info) The field settings on the original and the copied field configurations will be identical.

Note that a newly created Field Configuration will not take effect until it has been activated (see below).

Activating a Field Configuration

To activate a Field Configuration:

  1. configure a Field Configuration Scheme to associate the Field Configuration with appropriate issue types;
  2. then associate the Field Configuration Scheme with a project.

For details of both procedures, see Associating Field Behaviour with Issue Types.