Using custom fields with the Jira integration

TestRail’s advanced defect plugin for Jira enables teams to push new bug reports to Jira, lookup Jira issues, and integrate requirements and references. This document includes additional details on how to customize the integration with additional fields in the Push Defect dialog as well as additional issue links and sub-tasks.

Displayed fields

The Jira REST plugins allow you to configure and change the fields displayed in the Push Defect dialog and when link hovering. By default, the plugin already includes a list of fields as part of the default defect configuration (in the Defect and Reference configuration boxes under e.g. Administration > Integration or in a project’s integration settings.)

[push.fields]
summary=on
project=on
issuetype=on
# ...
          
[hover.fields]
summary=on
project=on
issuetype=on
# ...

You can enable & disable individual fields and also change the order of fields by adjusting the above configuration.

Field options

In addition to enabling or disabling fields as discussed above, it’s also possible to change additional options per field. To do this, you would define a section like [field.settings.components] to specify additional options for the component field. The following options are supported:

[field.settings.components]
label=Component
size=compact
remember=false
required=false
type=dropdown

You don’t need to specify all options though. If you just want to change the required option for a field, for example, you can skip the other options. Please see below for an explanation of the various options:

Custom fields

You can also use the above-mentioned approach to add custom fields defined in Jira to TestRail’s Push Defect dialog and while link hovering. To do this, simply add a line like this to the [push.fields] or [hover.fields] section to add a field:

[push.fields]
summary=on
# ...
customfield_11002=on
# ...

Note the name of the field. A Jira custom field always needs to be specified using customfield_<id>, where the ID is the ID of the custom field as defined in Jira. You can find out the ID of the custom field in Jira by editing the custom field in Jira’s administration area. The ID is part of the web address/URL of the edit page. In addition to enabling the field as specified above, you always need to add a corresponding field definition like this:

[field.settings.customfield_11002]
label=Customer
size=compact
type=dropdown
required=true

The following field types are supported (also note the possible mappings between Jira and TestRail fields):

Sub-tasks

The Jira REST defect plugin also supports sub-tasks. You can enable sub-task support with the a parent field as follows:

[push.fields]
parent=on

This will display a new Parent field on the Push dialog to enter a parent issue ID for new issues. If you also use the References field to link test cases to user stories or requirements stored in Jira, you can enable the following option to automatically pre-fill the Parent field with the value of the References field:

[push.field.parent]
autofill=on

Issue links

Starting with TestRail 4.0, the defect plugin also supports issue links. This can be used to create new issues that link to other existing issues in Jira. Issue links can be enabled as follows:

[push.fields]
# ...
linktype=on
links=on

This adds two new fields to the Push dialog (Link Type and Issue Links). The Link Type controls the type of link you want to create (e.g. “related to” or “duplicate of”). The Issue Links field allows you to enter a comma-separated list of Jira issue IDs you want to link to the new issue (using the configured link type).

If you also use the References field to link test cases to user stories or requirements stored in Jira, you can enable the following option to automatically pre-fill the Issue Links field with the value of the References field:

[push.field.links]
autofill=on

Please note:  if you get an error (e.g. 404) when trying to create new Jira issues with links, please make sure that the issue IDs you added to the Issue Links field exist in Jira.

Attachments

The Jira Defect Plugin supports submitting attachments to Jira as well. This field can be turned on and off, but cannot be customized. To submit one or more attachments to Jira, simply drag the attachment to the attachments or description areas of the push dialog or click on the area to choose an attachment from your file system.

Reference plugin

Reference plugins can be used to retrieve additional information from IDs entered into the References field of TestRail entities, such as test cases, test runs, and milestones. The Reference Plugin is configured on the References tab of the integration settings in the same manner the Defect Plugin is configured.

The plugin supports hovering over Reference IDs but does not support a Push dialog for the References field. It is also possible to customize the fields which appear via link hovering and add custom fields, as described above.

If you have the Defect Plugin already configured for Jira, you can simply copy your [connection] and [hover.fields] sections from the Defect Plugin into the Reference plugin configuration. Alternatively, you can choose different fields to be displayed for References and Defects.