How to Work with BTS Connectors

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

How to Work with BTS Connectors

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:

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 navigate to Account & Settings > Data Export.

  2. The Connectors List will be displayed.

BTS Issue Settings

Once you have enabled the BTS Integration for the product, selected the relevant BTS 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 to) 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 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.

BTS Issue Settings
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.

Mandatory vs. Optional Fields

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.

How to Add Optional Fields
  1. While in the Integration step of the Edit Product wizard, click on the “Add Field” button and select one of the available fields. 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 to the “Field Configuration” section. You may now continue to select its value: static, dynamic or custom.

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

How to Add Optional Fields

How to Remove Optional Fields

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

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

Selecting Values

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.

Static Values

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.
Static Values

Dynamic Values

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}”.
  3. To clear the selection, either select another field or click Clear
Dynamic Values

Text & Labels Field Values

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, that space characters 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.

Text & Labels Field Values

Custom Mappings

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.

Custom Mappings

Uploading Test Cycle Custom Fields

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.

Changing Test Cycle Custom Fields

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.