TFS Integration Platform – Explicit versus Implicit field mapping in the config … huh? Question & Answer 21

  • Article

Special thanks to Terry and Huyng from the TFS Integration Platform team for input and reviewing of this post!
Lime Green Man Wearing A Tie, Shaking Hands With Another Upon Agreement Of A Business Deal Clipart Illustration

Clipart Illustration of a Melting Mercury Meta Men Dripping All Over The Place, With Light Reflecting Off Of The Drops First of all let us clarify the difference between implicit and explicit in the context of field mapping, because this on its own has numbed a few brain cells in recent discussions. If we consult the online https://www.thefreedictionary.com dictionary, we get the following definition for implicit and explicit:

  • Implicit … “Implied or understood though not directly expressed”.
  • Explicit … “Fully and clearly expressed; leaving nothing implied”.

… so, when we say implicit field mapping we assume that although the configuration file does not show any field mappings, the fields are mapped and processed by the platform based on their names. If a work item X, in the source, contains fields A, B and C, the platform will implicitly look for a work item type with the same name and fields with the same names. When we refer to explicit field mapping, we imply that we have explicitly specified all of the fields to be processed as part of the configuration, possibly to map fields between two different work item templates. Here’s a visual representation of the mumbling above:
image

Thanks to the agile process and the continuous feedback from our test and proof of concept environments, the configuration file feature set has just been expanded again. Let us look at a few sample configuration files:

Example 1 - Implicit field mapping
image

Is everyone happy with doing

a configuration extract “WITSessionCustomSetting” section that defines a work item type “Task” and no field or value maps. This means that all of the fields of the work item type “Task” will implicitly be mapped from source to target.

<WITSessionCustomSetting xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="https://www.w3.org/2001/XMLSchema">
- <WorkItemTypes>
<WorkItemType LeftWorkItemTypeName="Task" RightWorkItemTypeName="Task" fieldMap=”@@ALL@@”/>
</WorkItemTypes>
<FieldMaps/>
    <ValueMaps/>
</WITSessionCustomSetting>

Note that as per the following schema that fieldMap name is mandatory and must either reference a valid map of use the special @@ALL@@ token to confirm implicit mapping for “all” fields.
image  
… above is an extract from the file: … \Core\TfsMigrationEntityModel\TfsMigrationEntityModel\Schemas\WitSessionSettingXmlSchema.xsd

Example 2 – Explicit field mapping
image

The example shows a configuration extract “WITSessionCustomSetting” section that defines a hypothetical work item type X to a work item type Y mapping, including a value map for the field C. You must define all the fields that must be mapped and processed, which means that fields not defined as part of an explicit map are not processed. It is important to understand this constraint, otherwise a lot of fields may disappear into a black hole during your next migration.

<WITSessionCustomSetting xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="https://www.w3.org/2001/XMLSchema">
- <WorkItemTypes>
<WorkItemType LeftWorkItemTypeName="X" RightWorkItemTypeName="Y" fieldMap="X_To_Y_FieldMap" />
</WorkItemTypes>
- <FieldMaps>
- <FieldMap name="X_To_Y_FieldMap">
- <MappedFields>
<MappedField MapFromSide="Left" LeftName="A" RightName="A" />
<MappedField MapFromSide="Left" LeftName="B" RightName="B" />
<MappedField MapFromSide="Left" LeftName="C" RightName="C" valueMap="C_ValueMap" />
</MappedFields>
</FieldMap>
</FieldMaps>
- <ValueMaps>
- <ValueMap name="C_ValueMap">
<Value LeftValue="1" RightValue="10" />
<Value LeftValue="2" RightValue="20" />
<Value LeftValue=" " RightValue="30" />
</ValueMap>
</ValueMaps>
</WITSessionCustomSetting>

Also have a look at TFS Integration Platform – Mapping Work Item Fields and Values: Questions & Answers 12 for mapping field values, TFS Integration Platform – Aggregated Fields: Question & Answer 17 for ways of aggregating fields, and TFS Integration Platform – @@MISSINGFIELD@@: Question & Answer 16 for ways of dealing with missing fields as part of the mapping process.

… but there is more, after the latest feature update.

Example 3 – Introducing the wildcard
image

The example shows the introduction of the wildcard feature, see line <MappedField MapFromSide="Left" LeftName="*" RightName="*" />.

This new feature allows us to:

  1. Create a field map, without having to explicitly mapping each and every field, as per example 2.
  2. As part of the wildcard mapping, which is analogous to the implicit mapping, we can also specify additional field mappings. Take special note of the following:
    • In the hypothetical example below we map the Priority field to the Impact field.
    • The most specific mapping rule is used, which means that the priority field map is more specific than wildcard mapping and respected as such.
    • If Impact exists in the source WITD, the example maps two source fields, i.e. Impact and Priority, to the same target field and may cause a migration time conflict.
  3. If we would want to map Priority from the source to both Priority and Impact in the target, we could use the field aggregation field mapping feature, as described in TFS Integration Platform – Aggregated Fields: Question & Answer 17.

<WITSessionCustomSetting xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="https://www.w3.org/2001/XMLSchema">
<Settings />
- <WorkItemTypes>
<WorkItemType LeftWorkItemTypeName="Bug_X" RightWorkItemTypeName="Bug_Y" fieldMap="BugX_To_BugY_FieldMap" />
</WorkItemTypes>
- <FieldMaps>
- <FieldMap name="BugX_To_BugY_FieldMap">
- <MappedFields>
<MappedField MapFromSide="Left" LeftName="*" RightName="*" />
<MappedField MapFromSide="Left" LeftName="Microsoft.VSTS.Common.Priority" RightName="Microsoft.VSTS.Common.Impact" valueMap="PriorityValueMap" />
</MappedFields>
<AggregatedFields />
</FieldMap>
</FieldMaps>
- <ValueMaps>
- <ValueMap name="PriorityValueMap">
<Value LeftValue="2" RightValue="1" />
</ValueMap>
</ValueMaps>
</WITSessionCustomSetting>

This latest feature creates the foundation for the creation of maps between WIs that share a common base, especially as most of the custom templates were created based on the standard process templates, such as CMMI or Agile.

Before we beam out of this post … Do you dislike the XML configuration files and hands-on editing thereof? If yes, watch this space …