You need to perform your migration with the TFS Integration Platform, and beforehand, you have to add a field named “TfsMigrationTool.ReflectedWorkItemId” to all your destination work item types (it is a String field). This field is documented here. Actually, all you have to do is add it to your target WITs. You don’t need to set up anything else since the TFS Integration tools will detected it and use it if found.

This field is very important because it contains which work item is at the origin of a migrated work item, enabling translations of WI links.

Note that the TFS Integration Platform itself doesn’t need this, it is optional, for it has its own database, but ReflectWILinks does need this value.


Open up the .config file and set the following values as appropriate :

  • TargetTfsUri: Url of the target TFS server TPC (destination of the migration)
  • SourceTfsUri: Url of the source TFS server TPC (origin of the migration)
  • ScopeQueryGuid: the GUID (*) of the Scope query, it should include all work items that have been migrated that potentially have links
  • TargetQueryGuid: the GUID (*) of the Target query, it should include those work items that have been migrated, and that you want to update (it should be a subset of the scope query)
  • AddMissingChangesets: toggle to enable/disable the detection and completion of changeset links. Should be disabled if source and destination servers aren’t the same.
  • AddMissingRelated: toggles the detection and completion of links between work items.
  • AddMissingOtherExternal: toggles the detection and completion of other types of links (seldom)

Note: Hyperlinks are always added if missing

* about queries GUID: you can use a Work Item query either private or public and save it on the TFS server, then access it properties from Visual Studio and grab the GUID from the displayed Url

(eg: vstfs:///WorkItemTracking/Query/1ff0cd09-bc05-4e0b-97ab-65c853865c89)



Simply start the executable ReflectWILinks.exe in a console Window.

Possible messages

Missing Hyperlinks in any target WI is considered abnormal and is reported as a warning. Because such links should not have been missed by the migration. Has someone added such a link after migration ?

For RelatedLinks (links between work items) many checks are performed:

  • can’t have same link twice between two WIs
  • unknown link type in target Team Project
  • missing Work Item when the target WI is not found (not migrated ?)


The following stats are computed and displayed on the console at the end of the run:

Related links: found {0} - existing {1} - crosslinks {2} - added {3}
Changeset links: found {0} - existing {1} - added {2}
External links: found {0} - existing {1} - added {2}

Crosslinks are simply links where both WIs are in the Target query, those links are added from the first WI found in the query and ignored from the second to avoid duplicates


If the following warning is displayed :

Warning: Work Item XXX has reached max number of links to restore

You’ll have to start the utility again. This is because work items are processed one by one, and if a single WI has more than 30 missing links, only the first 30 are created. The rest are ignored. Launching the utility with the same parameters solves the problem (it will execute fast because there won’t be many links to create).

Last edited Oct 29, 2012 at 11:04 PM by vlabatut, version 4


No comments yet.