Backtrace provides tools for customers to triage, prioritize and explore errors (crashes and exceptions) generated from their servers, applications, or games. Often organizations will have a corresponding issue tracking system, like Jira, Github Issues, Phabricator, or FogBugz, where they track and manage work items for the engineering teams. Backtrace provides techniques to create and link to issues in those third party issue tracking systems so that resolution of crashes and exceptions can be managed via these existing workflows, and controls on when to synchronize data between Backtrace and the target issue tracking systems.

Backtrace provides two main ways to integrate with 3rd party issue tracking systems:

1. Automated issue creation - Backtrace allows admin users to specify rules to automatically create an issue in the target system (like Jira) whenever an error was first seen, or every time an error is seen in a given Project. This is used by organizations that wants a corresponding Jira issue for every crash or exception that Backtrace receives (see Figure 1 below).
2. Manual issue creation - One of the actions in Backtrace's Triage view is to Create an Issue in Jira, Github Issues, or any other linked issue tracking system for a group of errors identified by a common fingerprint. This is used by organizations who want to sort through and prioritize incoming errors in Backtrace, and have issues associated depending on things like the severity or impact. In short, it allows for issues to be created only for those crashes that the teams want to track work progress on (see Figure 2 & Figure 3 below).

Figure 1 (below) - In the Project Settings view, an admin user can specify when to automatically create issues for Integrations.

Figure 2 (below) - In the Triage view, a project member can view linked issues and create additional issues via the Action Menu for crashes identified by a common fingerprint. Choose the name of an issue tracking integration (i.e. phabicator or JIRA TEST below) to create a new issue in that system.

Figure 3 (below) - After selecting an issue tracking integration (i.e. JIRA TEST), the user is presented with a dialog that allows them to enter some additional information, such as a "title" or other specific values for certain fields in the issue tracking system. The screenshot below shows "title" and "owner". Admin users can further customize this dialog for their users by managing Custom Fields in Step 1 of Manage the Integrations.

Backtrace also allows you to control when data is synchronized between the 2 systems. See Figure 4 below.

In the rest of this document, we will discuss how an admin user can create and manage these Integrations so that they can be used for automated or manual issue creation. 

Manage the Integrations

An admin user will need to create an Integration for the project they wan to connect to the issue tracking system. This action is performed under Project Settings / Integrations. 

Users will see a list of all Integrations configured for the project: 

Admin users can view the status of a given integration by expanding the row for the Integration in the table:

The admin can also create new Integrations for different target system or edit existing Integrations. Below you can see how to kick off the New Integration flow:

Step 1 - Connection Details

The following information is required to setup the Connection details for Integration with Jira: 

• Name (required): The name you want this Integration to be identified by. This will be used in the list of Integrations and on the list of manual actions to take.
• 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.
• Field for Main Body Text: The name of the field to add descriptive information about the error too. Usually the name is "Description".
• Custom Fields:  Backtrace allows you specify additional fields and values you wish to populate in 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, 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.
• Subject: Subject line of the Jira issue. Supports a number of macros to dynamically populate a proper Subject line for the issue

Step 2 - Payload Details 

After configuring Connection details, the admin user defines the payload for the Integration. This includes:

• One way sync configuration: Enable this setting if you want Backtrace State (Open, Resolved, Muted) and Assignee synced to the 3rd party system. If enabled, changes to these fields in Backtrace will be reflected on linked issues in the third-party system. Backtrace will attempt to automatically determine the mapping from issue State to third-party system. There are plans to allow the user to specify a mapping from Backtrace issue State (open, resolved, etc...) to the third-party. 
• Display Settings: Choose which information you want to include in the Description field. This includes common Backtrace information, as well as any specific attribute values that should be displayed.

Step 3 - Issue Creation & Data Sync Behavior

The admin can now specify if they want the system to automatically create new Issues in Jira when an error is seen. Issues are created after being run through a rule engine, where rules are defined in the Step 4.

• Data Sync - You can specify if you want to Sync changes to fingerprint assignee and state information from Backtrace to Jira, as well as if you want sync that information from Jira to Backtrace.
• Automated Actions - Would you like to automatically create issues? Select Yes if you want to further configure the system to automatically create issues for errors that are seen.
• Select when to trigger create: Specify if you want to create a issue for every error seen, or only for new errors seen.

Step 4 - Automated Creation Behavior Rules

Finally, the admin user can configure the rule engine to submit or filter out issue creation depending on the values of attributes that are submitted with the error. 

For example, let's say that you only want to have automated issues created only if the "buildType" attribute is equal to "stable". You would set up the following actions, in this order:

• "filter" on any attribute with the regular expression .*
• "submit" on the buildType attribute with the regular expression stable

If buildType equals stable, then "submit" is the last match, therefore the notification is sent. Otherwise, "filter" takes effect.

Attributes you wish to match against must be defined in the Attributes section of Project Settings. See Attributes for more information.

When you specify one or more submit/filter actions, the system goes from the top item in the list to the bottom, along the way checking the attribute you specify against the regular expression. If the last match is "submit", then the system will ultimately send the notification. If the last match is "filter", then it will not.

Additional Rules

• Attribute: Test against this custom attribute to determine if the action is taken. 
• Regular Expression: Test the attribute against this regular expression. 
• Target: For Mentions, specifies the user or channel to mention when the criteria are met. 
• Action: Specifies to submit or filter out the event if certain criteria are met, or to trigger a mention to a particular user. (e.g. @username on a service). If more than one submit/filter action is specified, then the last successful match on the list (from top down) takes effect.