Tools: JIRA integration customization

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 Pushed Defect dialog as well as additional issue links and sub tasks.

Displayed fields

The JIRA REST plugin allows you to configure and change the fields displayed in the Push Defect dialog. By default, the plugin already includes a list of fields as part of the default defect configuration (in the Defect Plugin configuration box under e.g. Administration > Integration):

[push.fields]
summary=on
project=on
issuetype=on
component=on
assignee=on
priority=on
affects_version=on
fix_version=off
estimate=off
labels=off
environment=off
description=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 [push.field.component] to specify additional options for the component field. The following options are supported:

[push.field.component]
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:

Option Description
label Specifies the display name of the field in the Push Defect dialog
size Specifies whether the field is displayed as a compact field (compact value) or uses the full width of the dialog (full value)
remember Specifies if previously selected values for this field should be remembered and restored the next time the Push Defect dialog is opened
required Specifies if this field is mandatory or optional and whether users are required to enter a value for this field in the Push Defect dialog
type Specifies the type of this field; please see section Custom fields below for a list of supported field types

Custom fields

You can also use the above mentioned approach to add custom fields defined in JIRA to TestRail's Push Defect dialog. To do this, simply add a line like this to the [push.fields] section to add a field:

[push.fields]
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:

[push.field.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):

Field Type Types in JIRA Description
string Text Field, Labels A small free-text field for up to 250 characters
text Text Field, Free Text Field A large free-text field without practical size limitations
dropdown Radio Buttons, Cascading Select, Select List A dropdown list that allows users to select one of multiple options
multiselect Multi Select, Multi Checkboxes Allows users to select multiple, pre-defined options

Sub-tasks

Starting with TestRail 3.1, the JIRA REST defect plugin also supports sub-tasks. You can enable sub-task support with the new 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

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.

Additional customizations

The JIRA defect plugin was built to work with a standard JIRA configuration (including JIRA OnDemand). TestRail allows you to customize the integration and please see the following articles for details on how to customize the integration: