The Integration Mapping Platform is the preferred method for moving from CQ to TFS. Moving any other way is suicide. The integration platform, out of the box, provides great information on doing a one to one migration from CQ to TFS, but it doesn’t help you migrate ClearQuest links. In this post I’ll walk you through how to migrate links, and how to migrate links from one type to another and the gotcha’s you’ll find along the way.
The first thing is that you need to understand the CQ Schema. You do not need to use the CQ Designer – you can learn everything you need just by creating queries. So to begin with you need to know what you want to migrate (obviously) but we’re talking about what the work item types are and their relationships to other work item types (records) in CQ. For this example, I will show you how to migrate a “ChangeRecord” with a related “WorkRecord”. These will be migrated to a Requirement work item in TFS with a child Task work item.
Figure 1 shows a small portion of the ChangeRecord type in ClearQuest.
The critical thing to note about this is that we are not referencing the WorkRecord as part of the relationship at all. We are referencing the WRList “Field_Reference” field type. And that’s another – ClearQuest is case sensitive. Note that as you create your XML configuration file.
Once you have this information you need to create the queries (yes, you need at least two queries to perform a migration with links). The first query should be the first part of the link (in this case the “Parent” part of the relationship) and should return only those records that are going to be Parent work items. In this case the query will return only ChangeRecords. The second query, should, obviously be the child part of the query. The query used in this example will return WorkRecords which have ChangeRecord “parents”.
Next you need to set the queries to use in the Integration Platform like so:
After this comes the mappings. This is a straightforward mapping exercise. Here you will note the mappings I mentioned previously. The last part, setting the link type has to be done in the XML itself. Select the XML tag at the bottom of the settings form.
By default (and this is really important – if you do not follow this step, the migration will succeed but the linking will fail) there is a single line that reads as follows:
<font size="2"><LinkTypeMapping LeftMigrationSourceUniqueId=<span class="str">"79841a53-d698-4107-a2df-5ff935e0e0c9"</span> LeftLinkType=<span class="str">"ClearQuestAdapter.LinkType.Duplicate"</span> RightLinkType=<span class="str">"Microsoft.TeamFoundation.Migration.TFS.LinkType.WorkItemToWorkItem"</span> RightMigrationSourceUniqueId=<span class="str">"c80d3b9a-a40e-4aa7-bfb2-7828971ac4f0"</span> /></font>
You can, in most cases safely delete this line, but don’t do it yet! First, if you are going to keep it, copy it. You want the Unique ID’s from both the left and right migration sources. Once you copy it change the link types as follows:
<font size="2"><LinkTypeMapping LeftMigrationSourceUniqueId=<span class="str">"79841a53-d698-4107-a2df-5ff935e0e0c9"</span> LeftLinkType=<span class="str">"ClearQuestAdapter.LinkType<font style="background-color: #ffff00">.ReferenceListFieldRecordLink.ChangeRecord.WRList</font>"</span> RightLinkType=<span class="str">"<font style="background-color: #ffff00">System.LinkTypes.Hierarchy</font>"</span> RightMigrationSourceUniqueId=<span class="str">"c80d3b9a-a40e-4aa7-bfb2-7828971ac4f0"</span> /></font>
There are two differences to note as highlighted. The first is that the reference link for CQ must specify the work item.work item list. In other words, the relationship isn’t ChangeRecord.WorkRecord but rather ChangeRecord.list type as shown in the first figure. The second item is that the WorkItemToWorkItem link is a hold over from the TFS 2008 migration provider. We’re passed that obviously. To convert the link from whatever link type in CQ to TFS simply use the TFS link type (to get a list of these, do a witadmin exportlinktype and take a look at the resulting file).
Please note that none of this is documented in the Integration Platform documentation. Hopefully this will be updated soon with this information. For now, this is how to do it.