Once your collection-to-model field mapping is complete, your next step is to configure each field. Tasktop will generally auto-configure these for you, but in certain cases (such as single-selects and multi-selects), additional configuration may be needed. In scenarios where the integration cannot run successfully without additional configuration, you will see an orange configuration warning next to that field.
To review and update an individual field's configuration, click the Configure link to its right. This will lead you to the Field Configuration screen:
The Field Configuration screen is where you can configure your transforms and value mappings.
Similar fields in different repositories often come in different formats, resulting in the need for values to be transformed to their proper format before flowing to the target repository. This screen allows you to configure how different types of fields will translate from one repository to the other.
You can learn more about Supported Transforms on the Field Mapping page.
The transform on the left will impact how data flows into your repository (from your model), and the transform on the right will impact how data flows into your model (from your repository).
Here are some examples of available transforms:
- Copy: A copy of the value from the source field will flow to this field. The value sent will over-write whatever was previously held in that field.
- Append: A copy of the value from the source field will flow to this field. Values that existed previously will remain, with the new value appended to the end. This transform is typically utilized within the context of a Modify via Gateway Integration.
- None: No value will flow from the source field to this field.
- (Field Type) to (Field Type), for example 'Formatted String to Rich Text': In some cases, you may need to transform the data from one field type (such as a Formatted String) to another field type (such as Rich Text). In this scenario, your transform will function similarly to the 'copy' transform. It will overwrite whatever values were previously held in that field with the new (transformed) value sent from the source field.
- Note that for transforms for multi- field types (i.e., multi-select, containers, relationships, etc), where appropriate, the values will be listed out and separated by a comma. For example, a "Containers to ID" transform will flow all container IDs, each separated by a comma, to a string field.
- Rich Text to Literal String and Literal String to Rich Text: While 'rich text to formatted string' strips the text of any code and outputs a human-readable string, 'rich text to literal string' outputs raw rich text data, preserving the rich text markup (for example, flowing '<b>bold</b>,' rather than 'bold'.
- Location to Web Link (Summary as Label): Some transforms allow Tasktop to perform some behind-the-scenes magic. For example, the 'Location to Web Link (Summary as Label)' transform will flow a location (i.e., the URL for an artifact) to a Web Link field, using the Summary field on that source artifact as the label for that hyperlink.
- Custom Data Transformations: If you have configured a Custom Data Transformation extension, you can apply it on this screen:
In most scenarios, the default setting will be appropriate, and you will not need to modify anything here.
Rich Text (Text Markup)
In order to ensure that rich text fields are formatted properly between repositories, the text markup language must be set appropriately. The good news is that Tasktop's default text markup configuration should cover most rich text scenarios.
You'll notice that the Text Markup field is automatically set to 'default.' You can leave this as-is for the majority of integration scenarios.
However, there may be cases where you'd like to customize the text markup language used. For example, you could be using a plug-in like JEditor - Rich Text Editor for Jira, which causes your repository to utilize an unexpected rich text markup language.
In cases like this, you can customize the desired text markup language. You'll see a wide range of text markup options available on this screen. Search for the one you need and select it here. The language selected will impact both how data flows into and out of the collection for that specific field.
Single- and Multi-Select Fields
When flowing single- and multi-select fields, Tasktop will need to know how to translate different field values between repositories. To handle this, Tasktop offers an easy-to-use field value mapping canvas on the Field Configuration screen.
If your field values have not yet been mapped, you'll notice an alert next to the Configure link on the Field Mapping screen:
Once you click Configure, you will be lead to the Field Configuration screen. Please review the sections below in order to learn which selections to make on this screen.
Transforms for Single- and Multi-Selects
In most single- and multi-select field scenarios, you will configure your transform as 'copy' on both the collection and on the model side. This means that the model will pass an identical copy of its value to the collection, and vice versa. This should be the default setting.
Field Value Mapping
If the Auto-map by label box is checked, Tasktop will use its built-in smarts to pre-map some of the field values for you based on their labels. If you'd like, you can click the trash can icon next to each mapping to remove the mapping, and then manually re-map them.
To complete the field value mapping, select the values in the collection and in the model that you would like to map to one another, and then click Connect. This process enables to the model to act as a 'translator' between two different collections which may have different sets of values for a single- or multi-select field.
When you map multiple collection values to a single model value, you will find that one value on the collection side is listed in brackets. This indicates which value will be written when the mapped model value is flowed to that field. In the scenario below, if the model passes a 'low' priority value to your collection, that artifact will default to a priority status of 'minor,' rather than 'trivial.' You can modify the default value by clicking the arrow icon on the collection field pill.
Note: If your model allows unmapped values to flow for the field you are configuring, you will see an indication of both the number of values that are explicitly mapped to your model, and the number of values that have been 'accepted' by your model. The values that have been 'accepted' are those unmapped values which have been allowed to flow as part of your integration. Note that in most scenarios, the recommended setting is not to allow unmapped values to flow. However, allowing unmapped values to flow can make sense in a few specific scenarios, such as an Enterprise Data Stream integration or in single select to string transforms, where there are many options available and you don't desire any normalization of the data flowing through.
Default Field Value Mapping
You can set a default field value for any unmapped value by going to the bottom of the Field Mapping screen and clicking Select Default Value. From the dropdown menu, you can select your default value, and any unmapped value will be set to this value.
If Field Values Vary by Project
By default, Tasktop retrieves field values from one sample project for mapping. In rare cases where values vary between projects, check the Retrieve field values from all projects box on the Collection configuration screen to retrieve all possible values. Be aware that retrieving values from all projects can take some time.
Specific Use Cases
There are a few specific scenarios that will require additional configuration
Some repositories require that a state transition be performed in order to update the value of certain fields (for example, when an artifact must move from a status of New to In Progress to Closed, but cannot move directly from New to Closed). If this is the case, you'll notice that the transform on the left for this field defaults to None. That is because Tasktop is unable to update that field, unless a state transition has been configured in Tasktop.
If you'd like to configure state transitions for that field, make sure that the field is mapped to the model, and then manually update the transform on the repository side (on the left) to Copy. Once the transform is updated, you'll see that the Configure State Transition link appears.
You can learn more about how to configure the state transition on the State Transitions page.
Single- or Multi-Select Fields with 25+ Possible Values
If you are mapping a single- or multi-select field that contains over 25 values, you will notice that a search box appears. This is to aid in performance and usability of the Field Configuration screen when mapping a large number of values.
Simply search for the field value you would like to map, and then click Add. This will add it to the mapping canvas, so that you can map those values as you normally would.
Relationship to Single-Select Transform
If desired, you can map a relationship on your source artifact to a single-select field on your target artifact. For example, you may wish to write the Jira Epic-link (relationship) to a custom single-select field in qTest Manager. To do this, you must map a relationship field in your source collection to a single-select field in your model.
- Ensure that your model includes a corresponding single-select field for the mapping
- In the source collection, click Map Fields and create a mapping from the collection's relationship field (Epic-Link in this example) to your model's single-select field.
- Once the fields are mapped, click the Configure link on the right side.
- Here you can search for the related Epics by their formatted ID, and click Add to add them to your canvas.
Note: if the artifact you are looking for has recently been created in your repository, click the Refresh button to refresh the artifacts that Tasktop is aware of. This will allow Tasktop to find that artifact.
- Once the related Epics are added to the canvas, map them to the available single-select fields in your model.
- Click Save and Done.
- Navigate to your target collection
- Map the target collection field to the single-select field in your model. Click configure to map the field values.
- Once you've configured your integration, your completed Integration Field Flow will look like this:
- When you run your integration, the single-select in your target repository will be updated based on the epic link (relationship) in your source repository.
- Here's the original user story in Jira. You can see that its Epic Link (a relationship to an associated Epic artifact) has flowed to the Jira Epic field (a single-select field) on the qTest Manager requirement: