This article provides general information about working with the BTS Connectors, as part of setting up the integration between the Applause platform and your Bug Tracking System.

For additional information about a specific BTS, see the links below:

• JIRA (v.5.0 or later)
  
  • Two-Way Jira Integration
  • Adding Statuses in My Jira for Two-Way Integration
  • Manually Creating a Jira Webhook
• Bugzilla
• GitHub
• FogBugz
• Mantis Bug Tracking (v.1.2.x or later)
• Azure DevOps (Microsoft TFS / Visual Studios Team Services)
  • Two-Way Azure DevOps Integration Setup
  • Adding Statuses in ADO for Two-Way Integration
• Pivotal Tracker
• Rally
• Redmine
• YouTrack
• Webhooks
• Email

 

How to View Your BTS Integration Connectors

The Connector List details all connectors set up for your company. The information displayed for each Connector includes the name, type and date/time of the last message processed (excluding connection testing). Once on the list, you can select a connector to view its configuration. To view the Connectors List:

1. Log in to the Applause platform and select a company from the company list.
2. Navigate to Configuration > Integrations and open the Connectors tab.
3. The Connectors list will be displayed.

 

BTS Issue Settings

Once you have selected the relevant BTS and product, and established a connection with your BTS, the issue settings within your BTS will be returned to the Applause platform. This allows you to configure what fields you would like to (or must) send to your BTS to appear in the created issue.

It’s important to note that when the integration is initially set, you are asked to establish the connection by clicking Test Connection. But, if the issue settings on your BTS have changed, you would need to refresh the connection and – depending on the change – to edit the field mapping. Click the Refresh Connection button to do so. This will re-establish the connection and provide the Applause platform with the latest issue settings from your BTS.

Note: To edit or delete an existing connector, click the icons at the top of the Connector Details page.

 

Fields, Values and Mappings

Defining the BTS Connector is essentially a field-mapping task. This will allow you to map the Applause platform fields to your BTS Issue fields so that the Applause value will be used when the issue is created in your BTS.

In some cases you may need to map between specific values, thus allowing dynamic creation of values in your BTS. And, in some cases, complete customization of the field value is allowed.

As part of the Issue Settings acquired from your BTS, a breakdown of mandatory and optional issue fields will be available for the Applause platform. The mandatory fields will populate the page and cannot be removed. Optional fields can be added and removed as needed.

1. While in the Connector Field Mappings section of the connector edit page, click on the “Add Field” button and select one of the available fields.
   1. If your BTS settings include fields that are not available in the list you may need to refresh the connection, then try again.
   2. The field will be added and you may now continue to select its value.

Note: Fields are added in an alphabetical order, which may differ from the way fields are presented in your BTS.

To remove an optional field, click the X icon to the right of the field.

Note: Fields that do not have this icon are mandatory and cannot be removed.

Once the field is selected, you will need to set the value that will be sent to your BTS. There are two types of values: static and dynamic.

To send a static value for a particular field, click on the dropdown list next to the field name and select the static value. The selected value will be sent for all issues sent from the Applause platform to your BTS.

A common example of static value will be a “Created By”. Many times users like to have issues created by the integration to be identified as such. In that case, you may want to map the integration user for this field as a static value.

Note: Static value mapping is only allowed for fields with a predefined list of values.

To map a static value:

1. While setting a field (either mandatory or optional), click on the dropdown list next to the field name.
2. Select the BTS value.

Some fields support the mapping of dynamic values. In these cases, the BTS field is mapped to an Applause field and the field value is pulled from the Applause platform. As the intent of the integration is to create the new issues in your BTS with their relevant, accurate information, most probably most of your field mappings will be of dynamic fields.

Common examples of dynamic fields will be “Action taken”, “Expected Result” and “Actual Result”.

To map a dynamic value:

1. While setting a field (either mandatory or optional), click on the dropdown list next to the field name and select the Applause field.
2. The dynamic value will be displayed as “${field name}”. (See the full list of field codes here.)
3. To clear the selection, either select another field or click Clear.

Two field types - text and labels - allow for unique customization – where sent values may be any combination of both static and dynamic values. For text fields, such as the issue subject (or title) and its description, this enables you to display several Applause field values in a single BTS field; for labels fields, this allows you to send multiple values commonly separated by space characters. In both cases, the customization allows for both static values, entered as free text, as well as dynamic values of multiple Applause fields.

Common examples will be:

• Construct the issue subject from the Applause Bug Subject, Bug Id, Severity and Type. For instance, “Bug #1234: Nothing works (Critical – Functional)”
• Construct the issue description to include all reproduction steps, including steps taken, expected results and actual results
• Label the exported issue with multiple labels, including a label based off the Applause product component, or even the value of a custom field

To map a text field value:

1. While mapping the text fields, click on the dropdown list next to the field name and select [Custom…].
2. The content text box will be displayed. You may type in whatever free text as a static value.
3. To add a dynamic value, use the dropdown list to the right of the unique value text box and select the Applause field.
4. The dynamic value will be displayed as “${field name}”. You may do this multiple times and add several Applause fields.

Note: Specifically for the Issue Description, in addition to the customization allowed, there are three default template options – Full, Compact, Bare Minimum – you may choose from.

To map a Labels field value, essentially follow the same steps. You should not, however, use space characters; they will be used to separate multiple values. In case the dynamic field value includes spaces this may result with a large number of label values.

In addition to static and dynamic value mapping, at times you may need a more advanced mapping. Custom mappings allow you to map specific field values in Applause platform to the matching field values in your BTS. This allows you to “translate” the Applause value assignment to your BTS’ “language”.

A common example of custom mapping will be for assigning the values of the “Priority” field in your BTS from values of the Applause field “Severity”.

To custom-map values:

1. While setting a field (either mandatory or optional), click on the dropdown list next to the field name and select [Custom…].
2. The option to select an Applause field will be displayed. Select one of the available fields: Severity, Bug Type, Approval Value Tier, Frequency or any uploaded test cycle custom field (see below).
3. The values of the selected Applause field will be displayed. Next to each of the fields, select a matching value of the BTS field you are setting. Note that you are able to map the same BTS field value to multiple Applause values.

Once all fields are selected and values are mapped, remember to save the product settings.

As you set the Custom Mapping you may want to use values set for issues by the testers for custom fields set on test cycles. Using the custom fields in your mapping allows you virtually unlimited options for collecting issue-level data from the testers and have it included in the issues when those are created in your BTS.

Note: Learn more about adding custom fields while creating or editing test cycles here.

In order to populate the list of fields available for custom mapping, you’ll need to upload them from the test cycle. Follow these steps:

1. While setting the BTS Connector, click to expand the My Test Cycle Custom Fields option.
2. Select an option for “Map Field Options by”:
   
   • Value - works across cloned test cycles, however option value (text) cannot be ever edited.
   • ID - works only for bugs from the exact test cycle where a custom field was created, doesn’t work for cloned test cycles. Option values (text) can be edited any time.
3. Input the test cycle ID and click Load Custom Fields.
4. If the fields were uploaded successfully, a message will be displayed and the fields are available for selection in the list of fields available for custom mapping.

In case the connector has been created with custom fields uploaded from a certain cycle, and now the mapping needs to be changed (i.e. upload other custom field, or same custom field from a different cycle, or simply change the upload type by ID/Label), then follow these steps:

1. Navigate to the connector.
2. Edit the connector, and uncheck the box next to “Include My Test Cycle Custom Fields”.
3. Save the Connector.
4. Edit the connector again.
5. Check the box next to “Include My Test Cycle Custom Fields” and complete the upload & field mapping.
6. Save the connector again.