Migrate TFS to a New Server – This Update Path IS Possible

Migrate TFS to a new server
The Scenario – Why Migrate TFS?

The officially recommended and supported way to move from an older version of TFS to a newer one is to do an in-place upgrade of your existing installation. There are many reasons, however, why you may prefer an option to migrate your existing TFS data to a new server. You may have a more powerful server you’d like to move TFS to. You may be trying to consolidate multiple projects into one centralized server. Maybe you have a huge repository you’ve been using forever and you’re simply afraid of what might happen if something with the upgrade goes wrong.

The Solution

The good news is, there is a TFS Integration Platform available to help you do migrations of TFS Version Control and Work Item Tracking from one server to another. This platform is developed by some of the same Microsoft folks that develop Team Foundation Server. And on top of that, as is mentioned in the Visual Studio Gallery, “The integration tools are fully supported by Microsoft Support and are the same tools Microsoft uses to keep data synchronized between our internal TFS servers”.

I recently got a chance to play around with the platform’s TFS Integration Tools (the latest stable Mar 2012 release at the time of this article) in a migration from an existing 2010 TFS instance to a new server running TFS 2012.

One of the big reasons we chose to migrate to a new TFS server rather than performing an in place upgrade was that the organization wanted to get all of the development groups using the same agile process template. Keeping all of your teams on the same template can serve several beneficial purposes. For managers, it facilitates uniform metrics reporting. For developers, project managers, SCRUM masters, etc., a consistent development methodology can make utilizing resources cross-project much simpler. For new employees and employees moving across teams, having one primary development workflow means quicker integration and productivity.

The TFS Integration Tool works well for this kind of migration. It’s set up with a few default templates you can select to migrate your version control and/or work item tracking. If you are coming from a different process template, you could create a new xml template based on one of these samples.  Then, in the template, you could properly map all of the fields from your source process template to your destination template. If you have many projects that use the same source template that significantly differs from the destination it might be a good idea to do this.  It’s good to know though, as you’ll see below, that it’s not strictly necessary to do so.


TFS Integration Tool custom XML settings

There is a special option you can include in your destination (or Right Source as they call it) xml in the TFS Integration Tool:

<CustomSetting SettingKey="EnableBypassRuleDataSubmission"
SettingValue="true" />

With this setting, everything will be copied from the source to the destination as-is, without performing lots of data validity tests. This works out well for our changing process template scenario, because you will likely have values in fields that do not belong in the new template. Rather than crashing the migration, it will still write the original values and you can then deal with them on the new system later on. One good example of this is if you have many items in TFS that were worked on by a user that is no longer part of your company. They’re not in your active directory anymore so you can’t add them as a valid user to TFS. This scenario could be quite a headache, but with this option enabled their old ID will still get assigned to their items properly.

Having appropriate permissions to the TFS server is also important when using the TFS Integration Tools to perform a migration. You really need “Team Foundation Service Group” permission or higher in TFS to make sure the mapping is able to be done fully. You can’t get around it for Work Item Tracking. For Version Control, in one test I ran I was able to fully move over all of a project’s source with only user-level access, but without the elevated permissions (which you need to be able to use the custom setting I mentioned above) the user names and other mappings did not come over very cleanly.

Post-Migration Cleanup

After you do a transfer using the option mentioned above, you will likely have to do a little manual cleanup. When an item in TFS includes data in a field that is not within the options of the current template, you can still open the item fine but you will see warning boxes indicating the inappropriate value. For example, you may have pulled in a state value of “Done” when the appropriate option in the current template is “Closed”. In cases like this, it’s a simple matter to write up a tfs query that displays all items with a state of “Done”.  Open the results of that query in excel, change all of the Done’s to “Closed”, and you’ll be all set.

I found in this particular “Done” to “Closed” case that there is a closed date field associated with the changing of an item to the Closed state. That date field does not get set if you change the State field directly from an invalid state to the Closed state. To get around that, I first changed them all to “Active” and then to closed.

Running through a few post-migration steps like this may be simpler than mucking about with the migration xml to get things mapped correctly when they’re being moved.

What’s Missing?

OK, now the downsides of using this tool. Unlike an in place-upgrade, not everything comes across perfectly. Dates are the biggest nuisance – many dates get restamped with the date that you perform the migration. This includes source control checkin dates, work item tracking change stamps, etc. But if any date does change, the tool usually appends the original date to the history info for the item so it’s not completely lost. Your tasks will all get new task id numbers too, so if you do any kind of commenting in titles or descriptions where you include task numbers they will be off. I found in this case, too, if you dig into the history info you are able to find that it appends the original task id’s.

Also keep in mind that the tool specifially states that it currently only supports TFS Version Control and Work Item Tracking from.  I found these moved over well, complete with test cases and attachments.  If you use any of the other TFS features, you may need to do some additional manual work.  Custom TFS queries are one thing I use frequently that it does not move over. I tried a couple of other tools available to do this sort of thing – TFSQueryUtil and Work Item Query Administration.  With both I was able to extract the queries out to files without too much grief, but neither one was able to get those queries back in to my new 2012 TFS server successfully.


The TFS integration Platform and its associated TFS Integration Tools are a good way to migrate your TFS data to a new server.  Remember that this tool cannot exactly mirror your existing TFS installation, so plan on doing at least a little manual work after the migration to get everything set up to your liking.  But if you can live with working around what the tool cannot do, you’ll be happy with what it can.  It definitely saved my team a lot of time in getting our junk set up in our new 2012 server.

Have any questions about the TFS Integration Tools?  How about any experiences using the tool that you’d like to share?  Feel free to comment below.

Leave a Reply

Your email address will not be published. Required fields are marked *