Running the TFS Migration and Synchronization Toolkit

29Feb08

The purpose of the TFS Migration and Synchronization Toolkit is to enable customers of Team Foundation Server (TFS) to build custom tools that enable migration and synchronization with other version control (VC) and work-item tracking (WIT) systems.

If you would like a provider implemented for your existing systems, I suggest that you add your vote on the codeplex project page. Subversion-TFS, TFS-TFS and HP/Mercury TestDirector-TFS have the most votes so far.

Recently I’ve been working on implementing my own provider for the toolkit to synchronise data between a legacy system and TFS Work Items. I’ll be honest and say that it’s not a trivial task.

The best places to start are:

Creating a WIT migration tool - which tells you the classes and interfaces that you need to implement, and
WSS to TFS tools - this is a sample provider that implements syncing between WSS (SharePoint) and TFS Work Items.

One of the issues that I came across when I started the MigrationConsole.exe utility was that the TFS web services were throwing SoapExceptions with the message: “Forcing rollback —> Forcing rollback —> Forcing rollback.” Which isn’t a very useful error message

Running the MigrationConsole.exe as a member of the [SERVER]Team Foundation Server Administrators group isn’t good enough. You have to be running as a member of the “[SERVER]Service Accounts” group, as they are the only users able to upload invalid work item update packages with the BypassRules=”1” flag set.

If you use the http://tfsserver:8080/WorkItemTracking/v1.0/ClientService.asmx web service directly, you can call the Update() method and bypass any rules that are set on a Work Item. This is useful if the system that you’re syncing from doesn’t have good data integrity rules and importing them into TFS puts the work item in an invalid state.

Once you read the documentation (oops.) and get over that hurdle, then the Migration & Sync toolkit seems to work as advertised.

These links are helpful in explaining how to call the ClientService.asmx, create an <InsertWorkItem> package and how the BypassRules flag works.

And here’s some source code that demonstrates how to do it: