TFS Integration Platform … Should I use field name of reference name when defining field maps? Q&A-36

I noticed an email thread on which Grant Holliday was addressing a TFS Integration Platform migration session  that did not go as expected. Looking at the eye of the problem the question users of the platform could have is whether to use work item field names or reference names.

What’s the difference?

If we open a process template using the Process Editor Power tool, we notice that each field has a name and a reference name:

The field name is a friendly name, whereas the field is referenced by its reference name, for example when defining rules and conditions.

So what should we use when creating a field map?

When defining a field map you must use the “Reference Name”, not the “Field Name”.

INCORRECT use of field names:

<MappedField LeftName="MSIT.Description" RightName="Description" MapFromSide="Left" />
<MappedField LeftName="MSIT.AutomationStatus" RightName="AutomationStatus" MapFromSide="Left" />

CORRECT use of reference names:

<MappedField LeftName="MSIT.Description" RightName="System.Description" MapFromSide="Left" />
<MappedField LeftName="MSIT.AutomationStatus" RightName="Microsoft.VSTS.TCM.AutomationStatus" MapFromSide="Left" />

Other related references

Comments (2)

  1. Dan Gawarecki says:

    Explaining the "why" of having to always do something is always appreciated, otherwise you're just like some grade-school religion classes I had.

  2. @Dan, good point. In future we will ellaborate more on the "why".

    As mentioned in the post, the incorrect use of field maps results in unexpected behaviour, for example data not migrating as expected or migrations failing,