TFS Integration Tools – Where does one start? … part 4 (Mapping users the easy way)

We continue from TFS Integration Tools – Where does one start? … part 1 (documentation), TFS Integration Tools – Where does one start? … part 2 (try a simple migration) and TFS Integration Tools – Where does one start? … part 3 (dust has settled …. did it work?).

In this post we will look at addressing one of the gremlins we encountered in TFS Integration Tools – Where does one start? … part 3 (dust has settled …. did it work?), by using field and value mapping to map users from the source (from) system to the target (to ) system.

To recap … what is the problem we are trying to solve?

On our source (from) system my credentials are known as Willy-Peter Schaub, but on the target these do not exist. For arguments sake, let us assume that we are migrating from a Team Project using domain credentials to a Team Project using LiveID. The migration moves the field values, including assigned to, “as is”, not knowing that the user is not valid on the target system.

How do we change the configuration?

We have the option of the translation service referred to in the previous post of this mini-series, or simply using the configuration and adding a field and value map as shown:

  1. <WITSessionCustomSetting>
  2.    <Settings />
  3.    <WorkItemTypes>
  4.      <WorkItemType LeftWorkItemTypeName="Bug" RightWorkItemTypeName="Bug" fieldMap="GenericFieldMap" />
  5.      <WorkItemType LeftWorkItemTypeName="Task" RightWorkItemTypeName="Task" fieldMap="GenericFieldMap" />
  6.      <WorkItemType LeftWorkItemTypeName="Test Case" RightWorkItemTypeName="Test Case" fieldMap="GenericFieldMap" />
  7.      <WorkItemType LeftWorkItemTypeName="Sprint" RightWorkItemTypeName="Sprint" fieldMap="GenericFieldMap" />
  8.      <WorkItemType LeftWorkItemTypeName="Product Backlog Item" RightWorkItemTypeName="Product Backlog Item"
  9.                    fieldMap="GenericFieldMap" />
  10.    </WorkItemTypes>
  11.    <FieldMaps>
  12.      <FieldMap name="GenericFieldMap">
  13.        <MappedFields>
  14.          <MappedField LeftName="*" RightName="*" MapFromSide="Left" valueMap="" />
  15.          <MappedField LeftName="System.AssignedTo" RightName="System.AssignedTo" MapFromSide="Left" valueMap="UserMap" />
  16.        </MappedFields>
  17.      </FieldMap>
  18.    </FieldMaps>
  19.    <ValueMaps>
  20.      <ValueMap name="UserMap">
  21.        <Value LeftValue="Willy-Peter Schaub" RightValue="Willy@cave.co.za" />
  22.      </ValueMap>
  23.    </ValueMaps>
  24. </WITSessionCustomSetting>

In essence we define that:

  • Lines 3-10: We want to process the Bug, Task, Test Case, Sprint and Product Backlog work item types, each referring to the GenericFieldMap.
  • Lines 11-18: Each work item type must be mapped using the GenericFieldMap, which defines that all fields must be mapped as is *->*, except for the AssignedTo field.
  • Lines 19-23: If the left value for the AssignedTo field is “Willy-Peter Schaub”, the value map defines a mapping to Willy@cave.co.za.

… the result is that the Assigned To field of the same WI is (1) mapped to the correct user when we re-run the migration against another team project, using (2) a different migration user.

Any new gremlins to be aware of?

Yes, the value mapping is currently case sensitive. See Why is my user value mapping only working partially? Q&A-54 for more information.

Hope these blogs posts have made a few cloudy features a bit clearer in your mind. Let me know what else we should explore in greater detail than we have in the range of TFS Integration Platform – Summary of Links posts.