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 Hub how to flow information to and from your collection.

Mapping Fields

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

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. Hub 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.

 Tip: If you need to refresh the fields available for the collection, use the Refresh Fields button in the Hub UI, rather than your browser's refresh button.

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

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 Hub.

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

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

You can even filter by Collection to see the specific field labels and field types for that 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.

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

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.

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:

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

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

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.

 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.

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. Hub 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.

You can learn more about Field Configuration on the Field Configuration page of our User Guide.