Field Configuration

Introduction

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.

Configuration Warning

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:

Field Configuration Screen

Transforms 

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.

Field Configuration Screen

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 out of your repository (into your model).

Applying a TransformTransform from Repository to ModelTransform from Model to RepositoryTransform from Source to Target 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.

  • 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: 

Select Data Transformation Extension

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 instance, 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.  

Text Markup Configuration - in most scenarios this should be left as 'default'

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:

Configuration Warning for Single Select

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.

Field Mapping 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' magic wand 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.

Map Single Select Field Values

This image helps illustrate what your Collection-to-Model Field Mapping does.(lightbulb) 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.

Default Value for Single-Select Mapping

(lightbulb) 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.

Mapped vs. Accepted

Specific Use Cases

There are a few specific scenarios that will require additional configuration

State Transitions

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.

Update Transform

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.

Search for Field Value

Click 'Add'

Field Added to Canvas for Mapping

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 QASymphony qTest Manager.  In order to do that, you must map a relationship field in your source collection to a single-select field in your model.

  1. Ensure that your model includes a corresponding single-select field for the mapping
    Add Single-Select Field to Model
  2. In the source collection, click on 'Map Fields,' and create a mapping from the collection's relationship field (Epic-Link in this example) to your model's single-select field.
    Select Relationship Field in CollectionSelect Single-Select Field in ModelCreate Mapping
  3. Once the fields are mapped, click the 'Configure' link on the right side
  4. 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.
    Add Artifact to Canvas
  5. Once the related Epics are added to the canvas, map them to the available single-select fields in your model.
    Map Epics to ModelMapping is Complete
  6. Click 'Save' and 'Done.'
  7. Navigate to your target collection
  8. Map the target collection field to the single-select field in your model.  Click configure to map the field values.
    Map Single Select to ModelConfigure Field MappingField Mappings
  9. Once you've configured your integration, your completed Integration Field Flow will look like this:
    Completed Integration Field Flow

  10. 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.
  11. 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 QASymphony qTest Manager requirement:
    Story in JiraTarget Artifact in QASymphony qTest Manager

Next Steps

Once you have completed your Field Mapping and Field Configuration, your next step will be to review your collection's Relationship Specification.