Field Mapping

Introduction

After saving your Work Item Collection (Repository), the next step is to map fields from your collection to your model.  This will tell Tasktop how to flow information to and from your collection.

How to Map Fields

After saving your Work Item Collection (Repository), you'll see that the 'Map Fields' link becomes active.

Click 'Map Fields'

Clicking this link will take you to a drill in page where you can specify how the fields in your model will map to the fields available on the artifact within your repository. Tasktop will auto-map fields when possible based on the names of fields and the smart field designations that have been set in a given model.

(lightbulb) Tip: If you need to refresh the fields available for the collection, use the refresh button to the right of 'Suggest Mappings,' rather than your browser's 'refresh' button.

Refresh Artifact Schema

You can map additional fields by using the two drop down boxes:

Mapping Additional Fields

Transforms

When you map a collection field to a model field, it is necessary to transform the data from the source field to the target field.  Depending on the field types, that transform may or may not be possible within Tasktop Integration Hub.

You can see a table of the available transforms by clicking the 'Data Transformations Screen' link on the Help page.

'Data Transformations Screen' Link

This will lead you to the Field Value Transformations screen.  Here, you can see which collection-to-model field type transformations are available.

Field Value Transformations Screen

You can even filter by Collection to see the specific field labels and field types for that collection:

Filter Field Value Transformations by Collection

Transform Table filtered by Collection

On the Field Mapping screen, if you attempt to map fields that do not have a valid transform between one another (for example, if you map 'due date,' a date field, to 'status,' a single-select field), you will get an 'invalid mapping' warning, and the mapping will not be saved.

Invalid Mapping Warning

To help troubleshoot, you can review the field type when selecting each value from the drop down menu. This will enable you to ensure that the transform between the two field types is supported.

Field Types

Field Mapping Icons

On the Field Mapping screen, you will see a number of icons which will help you understand any special properties or requirements for each field. If you hover your mouse over an icon, you will see a pop-up explaining what the icon means. You can also review their meanings in the legend below:

IconMeaning
Constant Value Icon

A constant value will be sent. Note that:

  • If the icon is on the side of the collection, this means that a constant value will be sent to your model. This means that any time this collection is integrated with another collection, the other collection will receive this constant value for the field in question.
  • If the icon is on the side of the model, this means a constant value will be sent to your collection. This means that any time this collection is integrated with another collection, that this collection will receive the constant value for the field in question.

A state transition will be utilized. Note that:

Read Only Icon
Repository field is read-only and cannot receive data.
Required for Creation Icon
To create artifacts in your repository, this field must be mapped to your model.
Required Icon
This is a required field in your model; it must be mapped to your collection.
Prohibited Icon
This field will not be updated as part of your integration because the mapping would be invalid. You do not have the option of changing this.


Constant Value Mapping 

In some scenarios, either the collection artifact or the model might require that a value be provided for a given field. This value is usually provided by mapping it to the equivalent field in the collection or model. However, sometimes your collection artifact has a field that needs a value that doesn't align with any fields in your model, and sometimes your model might have a required field that doesn't have an equivalent field from the collection artifact. In these cases, you can set a constant value. By doing so, you'll specify the value that you would like to provide for that field.

Constant values can be set for the following field types:

  • Boolean
  • Date/DateTime
  • Double
  • Location
  • Long
  • Multi-Select
  • Person
  • Rich Text
  • Single-Select
  • String

Scenario 1: If your repository requires a field for artifact creation, but that field is not a part of your model:

Solution: Set a constant value on the side of the model, to send to your collection.

To set a constant value for a field, select 'Constant Value' from the drop down menu on the model side. Enter the value, and then click the 'Set Constant Value' box.

Setting Constant Value on Model Side

Setting Constant Value on Model Side, Cont.

Click 'Set Constant Value'

Constant Value is Set

Once the constant value is set, you will notice a few things:

  • The pill will be rectangular and grey: this denotes that a constant value has been set.
  • The Constant Value icon will be displayed inside the pill.
  • The 'prohibited' icon will appear next to the pill. This indicates that no values can be sent to the Constant Value field. The constant value is essentially a dead end, and cannot be linked to a repository or model on the other side.

In the scenario above, any time a new defect is created in Jira, the priority will be set to 'Major.' Jira will not send 'priority' data to any other collections, as 'priority' is not mapped to the model.

Constant Values per Project

If desired, you can also set constant values per project.

You may wish to set a constant value based on project in the following scenarios:

  • In order to set a unique value for a specific field, such as release or iteration, depending on the project
  • If the values for a single-select field vary across projects

To do this, select 'Constant Value Based on Projects':

Set Constant Value based on Projects

Once selected, you will see an orange exclamation point appear next to the 'Configure' link:

Click 'Configure'

Click "Configure" to get to the Configuration Screen. On this screen, you will be able to set a distinct constant value for each project in your collection:

Set Constant Values based on Project

In the screenshot above, a bug created in the Desktop Project would have the value 'Desktop' applied to the Component(s) field, while a bug created in the 'Mobile Project' would have the value 'Mobile App' applied to the Component(s) field, and finally a bug created in the Web project would have the value 'Web' applied to the Component(s) field.

Constant Value based on projects is configured

 

Once the constant value is set, you will notice a few things:

  • The pill will be rectangular and grey: this denotes that a constant value has been set.
  • The Constant Value icon will be displayed inside the pill.
  • The 'prohibited' icon will appear next to the pill. This indicates that no values can be sent to the Constant Value field. The constant value is essentially a dead end, and cannot be linked to a repository or model on the other side.

Note: Sometimes, a single-select field in your collection will not return any values to be selected in in the UI. In cases when this is true, and when the artifact will accept new values for that field, you will see a text input in which you can configure a constant string value (instead of the traditional drop-down list for a single-select).

Scenario 2: If your model requires a field, but the repository utilized in your collection does not have that field:

Solution: Set a constant value on the collection side to send to your model. This means that any time your source collection creates a corresponding artifact in a target collection, the field will automatically be set to the constant value in the target repository.

To set a constant value for a field, select 'Constant Value' from the drop down menu on the collection side. Enter the value, and then click the 'Set Constant Value' box.

Constant Value Set on Collection Side

 Once the constant value is set, you will notice a couple of things:

  • The pill will be rectangular and grey: this denotes that a constant value has been set.
  • The Constant Value icon will be displayed inside the pill.
  • The 'prohibited' icon will appear next to the pill. This indicates that no values can be sent to the Constant Value field. This makes sense, because in this example your repository did not have a 'severity' field to begin with.

In the example above, any defects that flow from Jira to a target repository will populate the 'Severity' field in the target repository with a value of 'Sev 3.'

Field Configuration

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.  You can learn more about Field Configuration on the Field Configuration page of our User Guide.