As you have already seen, fields are used to capture and display data in JIRA. Fields can also have behaviors, which are defined by field configuration. For each field in JIRA, you can configure its behaviors listed as follows:
- Field description: This is the description text that appears under the field when an issue is edited. With field configuration, you can have different description texts for different projects and issue types.
- Visibility: This determines if a field should be visible or hidden.
- Required: This specifies if a field will be optional or required to have a value when an issue is being created/updated. When applied to a select, checkbox, or radio button custom fields, this will remove the None option from the list.
- Rendering: This specifies how the content is to be rendered for text-based fields (for example, wiki renderer or simple text renderer for text fields).
A field configuration provides you with control over each individual field in your JIRA, including both built-in and custom fields. Since it is usually a good practice to reuse the same set of fields instead of creating new ones for every project, JIRA allows you to create multiple field configurations, with which we can specify different behaviors on the same set of fields and apply them to different projects.
We will be looking at how to manage and apply multiple field configurations in the later sections of this chapter. But first, let's take a close look at how to create new field configurations and what we can do with them.
You can access the field configuration management page through the JIRA administration console:
- Browse to the JIRA administration console.
- Select the Issues tab and then the Field configurations option. This will bring you to the View Field Configurations page.
Creating new field configurations is simple. All you need to do is specify the name and the short description for the new configuration:
- Browse to the View Field Configurations page.
- Click on the Add Field Configuration button.
- Enter the name and description for the new field configuration.
- Click on the Add button to create a field configuration.
As we will see later in the Field Configuration Scheme section, field configurations are linked to issue types, so it is recommended to name them based on the issue type they will be applied to and with a version number at the end, for example, Bugs Field Configuration 1.0. This way, when you need to make changes to the field configuration, you can increment the version number, leaving a history of changes you can revert to.
After a field configuration is created, it is not put to use until we associate it with a field configuration scheme. We will look at how to do this in later sections.
Now that we have seen how to create new field configurations, it is time for us to take a closer look at the different configuration options. Just a quick recap - each field configuration includes all the fields available in JIRA, and its behavior is defined specifically to each field configuration. We will then associate it with a field configuration scheme, which will determine when a field configuration will become active for a given issue.
Perform the following steps to access the field configuration options:
- Browse to the View Field Configurations page.
- Click on the Configure link for the field configuration you wish to configure. This will take you to the View Field Configuration page.
On this page, all the fields and their current configuration options that are currently set for the selected field configuration are listed:
As you can see, there are several options you can configure for each field, and depending on the field type, the options may vary. While we will be looking at each of the options, it is important to note that some of the options will override each other. This is JIRA trying to protect you from accidentally creating a configuration combination that will break your system. For example, if a field is set to both hidden and required, your users will not be able to create or edit issues, so JIRA will not allow you to set a field to required if you have already set it to hidden.
While having a meaningful name for your fields will help your users understand what the fields are for, providing a short description will provide more context and meaning. Field descriptions are displayed under the fields when you create or edit an issue. To add a description for a field, do the following:
- Browse to the View Field Configuration page for the field configuration you wish to use.
- Click on the Edit link for the field you wish to set a description for.
- Add a description for the field, and click on Update.
You can set certain fields as required or mandatory for issues. This is a very useful feature as it ensures that critical information can be captured when users create issues. For example, for our support system, it makes sense to have our users enter in the system that is misbehaving in a field and make that field compulsory to help our support engineers.
You have already seen required fields in action. System fields, such as Summary and Issue Type, are compulsory in JIRA (and you cannot change that). When you do not specify a value for a required field, JIRA will display an error message underneath the field, telling you that the value is required.
When you add a new field into JIRA, such as custom fields, it is optional by default, meaning users do not need to specify a value. You can then change the setting to make those fields required:
- Browse to the View Field Configuration page for the field configuration you wish to use.
- Click on the Required/Optional link for the field you wish to set as the mandatory requirement.
You will notice that once a field is set to required, there will be a small required text label in red next to the field name. When you create or edit an issue, the field will have a red * character next to its name. This is JIRA's way of indicating that a field is mandatory.
Most fields in JIRA can be hidden from user's view. When a field is set to hidden, users will not see the fields on any screens, including issues such as create, update, and view. Perform the following steps to show or hide a field:
- Browse to the View Field Configuration page for the field configuration you wish to use.
- Click on the Show/Hide link for the field you wish to show or hide, respectively.
Once a field has been set to hidden, it will not appear on screen and you will not be able to search in it. However, you can still use tools such as scripts to set values for hidden fields. For this reason, hidden fields are used to store data that is used by automated processes.
Not all fields can be hidden. Built-in fields, such as Summary and Issue Type, cannot be hidden. When you set a field to hidden, you will notice that you can no longer set the field as required. As stated earlier, setting a field to required will make JIRA enforce a value to be entered into the field when you create or edit an issue. If the field is hidden, there will be no way for you to set a value and you will be stuck. This is why JIRA will automatically disable the required option, especially if you have already hidden a field. On the other hand, if you marked a field as required, when you hide the same field, you will notice that the field is no longer required. The rule of thumb is that field visibility will override field requirement.
Renderers control how a field will be displayed when it is being viewed or edited. Some built-in and custom fields have more than one renderer, and for these fields, you can choose which one to use. For example, for text-based fields, such as Description, you can choose to use the simple text renderer or the more sophisticated wiki-style renderer that will allow you to use wiki markup to add more styling.
JIRA ships with four different renderers:
- Default text renderer: This is the default renderer for text-based fields. Contents are rendered as plain text. If the text resolves a JIRA issue key, the renderer will automatically turn that into an HTML link.
- Wiki style renderer: This is an enhanced renderer for text-based fields. It allows you to use wiki markup to decorate your text content.
- Select list renderer: This is the default renderer for selection-based fields. It is rendered as a standard HTML select list.
- Autocomplete renderer: This is an enhanced renderer for selection-based fields, and it provides an autocomplete feature to assist users as they start typing into the fields.
The following table lists all the fields that can have special renders configured and their available options:
|
Field |
Available renderers |
|
Description |
This is a wiki-style renderer and default text renderer. |
|
Comment |
This is a wiki-style renderer and default text renderer. |
|
Environment |
This is a wiki-style renderer and default text renderer. |
|
Component |
This is an autocomplete renderer and select list renderer. |
|
Affects version |
This is an autocomplete renderer and select list renderer. |
|
Fix versions |
This is an autocomplete renderer and select list renderer. |
|
Custom field of type |
This is a wiki-style renderer and default text renderer. |
|
Custom field of type |
This is a wiki-style renderer and default text renderer. |
|
Custom field of type |
This is an autocomplete renderer and select list renderer. |
|
Custom field of type |
This is an autocomplete renderer and select list renderer. |
Perform the following steps to set the renderer for a field:
- Browse the View Field Configuration page for the field configuration you wish to use.
- Click on the Renderer link for the field you wish to set a renderer for (if it is available). You will be taken to the Edit Field Renderer page.
- Select the renderer from the available drop-down list.
- Click on the Update button to set the renderer.
There are other custom renderers developed by third-party vendors. Just like custom fields, these are packaged as add-ons that you can install in JIRA. Once installed, these custom renderers will be available for the selection of the appropriate field types.
A good example is the JEditor plugin, which provides a rich-text editor for all text-based fields such as Description.