David Boschmans' Weblog

Migrating from ClearQuest to Team Foundation Server work items

The last couple of days I've been closely working with a Microsoft Partner with an ISV/Software Solutions Competency on the migration of their Rational ClearQuest entities to Team Foundation Server. To safely move all the ClearQuest assets we have been using the CQConverter.exe utility. The CQConverter.exe utility (and its .config file) is part of TFS and can be found in the C:\Program Files\Microsoft Visual Studio 8\Common7\IDE folder.

A well-documented walkthrough "Walkthrough: Migrating ClearQuest Work Items to Team Foundation" on how to migrate ClearQuest Work Items to Team Foundation can be found on http://msdn2.microsoft.com/en-us/library/ms181248.aspx. Actually after you have prepared the migration the hardest work is done. The major steps are:

• Configure the migration process: edit the configuration files to guide the migration process.
• Analyze your ClearQuest database: run the ClearQuest converter to analyze your current ClearQuest database. The analysis produces a report and a set of files that describes the work items present in ClearQuest.
• Define the migration mapping: edit the XML files generated during the ClearQuest Database analysis to customize the migration process.
• Migrate your ClearQuest database to Team Foundation work item tracking:  use the configuration and mapping files generated during the analysis of the database to migrate your data.
• Review the migration report: discover the cause of any errors and warnings encountered during the migration, and review the migration status.

Despite the steps listed above look relatively easy, we struggled with some security issues and a compatibility issue between the CQConverter.exe utility and the ClearQuest client.

When executing CQConverter.exe I received the following error: "TF61016: The user "username" is not a member of 'Service Accounts group' ". However trying to add the user to the Service Accounts Group (through the Team Explorer) the Add button is grayed out; so there's no way to add the user to the Service Accounts Group. This issue is also listed on the "Visual Studio 2005 Team Foundation Server Beta 3 Refresh Known Issues" page. But I don't think the answer is really clarifying. So after some investgation it turns out that it's "by design" that CQConverter.exe must be run from a user account that is part of ‘Service Accounts’ group on TFS. The logical steps are: 

• figure out the user account from which the converter will be run.
• open Visual Studio Command Prompt.
• execute the following command: tfssecurity.exe /g+ "service accounts" /server:http://:

Why is this by design?

Well, the converter puts data from CQ into TFS. There may be rules in TFS that may cause that data to change.
E.g. if there is a rule that says CreatedDate should be the current date, or the CreatedBy field should be the user creating the bug.
The converter replays out the user action in TFS to migrate the bug.
E.g. if a bug went through active, resolved, close cycle then converter first opens a new bug in TFS, then resolves it and then closes it. You can see that this would create a problem with all the rules because CreatedDate would be set to the date the converter ran, loosing out the original date, and CreatedBy would be set to the user account running the converter.
So the converter runs in a mode where it bypasses those rules. The APIs exposing that functionality were deemed to be dangerous to be left open for normal users so the decision was made that only service account people would have access to those.

Another issue I faced is: "TF61103: The converter could not find the supported version of the ClearQuest client". The ClearQuest Client used is Rational ClearQuest MultiSite with BuildID 2003.06.13.402.000. Though this version is supported it turned out that it depends on the availability of the registry key HKCU\SOFTWARE\\Rational Software\\ClearQuest. So check if that key is available!

The ClearQuest Standalone client Version 2003.06.XX, where XX is the minor version is supported. In the Microsoft labs they have also done testing on 2003.06.12 versions of ClearQuest.
Versions 2002.05.20 and 2003.05.00 may also work, but have not been tested.

After solving these issues we were able to do a first test and get our ClearQuest entities migrated to Team Foundation Server work items. I'm pretty confident that at release time of TFS this tool will be of much use for migrating to Team Foundation Server!