This guide goes through the steps necessary to integrate Backtrace with Jira. Setting up integration with the Jira ticketing system requires a valid Jira REST API URL, as well as a valid username and password.
To set up the integration, first go to the Configuration page within the Web Console:
Next, select the project you want to add a integration for:
Then click Integrations in the left-hand menu, then Create a New Integration on the right, and pick the integration:
These are the settings that you can configure for your Jira integration:
- Jira API (required): Jira Endpoint URL (see below for examples)
- E-mail (required): E-mail associated with your Jira instance. For some users, the username of the Jira instance may be used.
- API Token (required): Jira API Token obtained here. Some Jira instances also support passwords in lieu of API Tokens, but that functionality is deprecated and will be removed.
- Project Key (required): Jira Project Key
- Issue Type: Jira Issue Type. Defaults to "Bug" if not present.
- Subject (required): Content to put in the "Summary" field of the ticket.
- Custom Field Mapping - Labels: See below
- Custom Field Mapping - Description: See below
- Custom Fields: See below
Jira Endpoint URL Examples
The Jira URL generally takes one of the following formats
- https://yourname.atlassian.net/rest/api/2/ (For Atlassian-hosted Jira sites)
For more detailed information, see The Jira API Documentation
Custom Field Mapping
Backtrace populates the default Jira labels and description fields. If you use a customized screen where these fields are removed or renamed, you will need to specify alternate field names for Backtrace to use to populate with data in the Custom Field Mapping configuration.
Make sure that the field specified for Labels uses the 'Labels' field type in Jira.
Backtrace also supports populating other custom Jira fields. This is useful when you are using a Jira screen with added custom fields that are required - if you don't populate these, then the integration will fail to create the Jira ticket.
The Custom Fields setting is an optional list of additional fields you wish to populate within your Jira issue. You can use the value of an attribute within the text by preceding it with $ (e.g. $version). For array-type fields (such as labels), separate values with commas. If an error group has more than one value for the specified attribute, the value with the highest count will be used.
You can use combinations of literal strings and attribute values. For example, you can set a field's value to "Hostname: $hostname, Version: $version" and the Jira integration will put the values of those attributes within the string, as expected.
Note: If you refer to an attribute within a custom field with the
$attribute syntax, but are not seeing the attribute populated within the field in Jira, make sure you've added this attribute to your Project Settings configuration under Attributes. See: https://help.backtrace.io/product-guide/attributes.
Backtrace requires the following fields, and automatically populates them based on your settings. You can override the content of any of these settings by specifying their value in the appropriate Backtrace Jira config setting, or by specifying it as a Custom Field
It is important to ensure that these fields are specified properly, as the Jira API will reject any request that has invalid fields or missing required fields.
- Project Key - This is specified by the "Project Key" setting.
- Summary - This is specified by the "Subject" setting.
- Issuetype - This is specified by the "Issue Type" setting, set to "Bug" by default.
- Labels - Backtrace assumes a labels-type field named "labels" and will populate this with the label "Backtrace", but you can override this by adding "labels" as a Custom Field. You can also specify an alternate name for this field with the Custom Field Mapping option.
- Description - Backtrace assumes a text field named "description" and populates this with the main error information, but you can override this by adding "description" as a Custom Field (not recommended). You can also specify an alternate name for this field with the Custom Field Mapping option.
For information on troubleshooting issues with your Jira integration, see: https://help.backtrace.io/troubleshooting/how-do-i-troubleshoot-a-backtrace-integration-with-jira-thats-failing
Next: After filling in the integration-specific settings, proceed to Common Settings to finish configuring the integration.