Migrating from TFS on-prem to TFService in the cloud

In this post, I will demonstrate how you can migrate your TFS on-prem to TFService in the cloud. This process will migrate your sources and your Work Items. You can visit their website to learn more about various support services. When you want to migrate from an on-prem version to the cloud, the only viable option is using the Integration Platform. Because using the Integration Platform can be challenging (if you Bing/Google the integration platform, you’ll see what I mean), I want to guide trough the required steps to perform a migration.

First things first, download and install the latest bits on the Visual Studio Gallery. The latest release is from March 2012, and actually is an update to the March 2011 release that adds support for TFS 2012 as well as fixes several important bugs that were reported.  It includes the ability to synchronize with the hosted Team Foundation Service at visualstudio.com. Next, you need to have a Team Explorer on your machine, which is included in every Visual Studio Version. Be sure to have at least SQL Express on your migration machine! In fact, the migration will look like this:



Before we start with the actual configuration of the Integration Platform, you need to set some permissions. If you don’t do this, the migration will fail immediately! That’s one of the parts that is not documented (at least, I didn’t find anything about that). What you need to do is making the user that will execute the migration is part of the Team Project Collection Service account group, both on the on-prem server as on TFService.  Unfortunately, you will find that the UI from TFS 2012 and TFService does not allow you to do this. You cannot add a user to that group. You have add the group to the user! So go to the Team Project Collection Administration page, select Security, go to the Users section and select your user. Go to Member of, and click Join Group


Add this user to the ‘Project Collection Proxy Service Accounts‘. Do this for both the on-prem TFS as TFService!


Integration Platform

Next step is the configuration of the Integration Platform. Open the Integration Tools and click on ‘Create New‘. This will open a file dialog asking you to select the template you want to use. In this case, we want to migrate both the Sources and the Work Items, so select the file “Team Foundation Server\VersionControlAndWorkItemTracking.xml“.  You will now see 4 parts that have to be completed:


Let’s start with Version Control. Click on the ‘Left Source – Configure” button. There you have to select the Team Project on the TFS On-prem server. Do the same for the right side. There you have to select the new (and probably empty) Team Project on TFService. You should now see the option to manage the Source Control paths. What I can suggest is the following: since the Team Project on TFService will also have BuildProcessTemplates folder, you will need to map the top-level folders one by one. Otherwise, you will have some conflicting changes when you run the actual migration. For example:


That’s it for Version Control. The next step is the Work Item Tracking. Again, select the on-prem Team Project for the left side, and the TFService Team Project on the right side. What you will now see is an additional section called ‘Queries‘. There you can select which Work Items need to be migrated. You can go as far as you want for that, you can for example use an existing (non-hierarchical) query from your on-prem Team Project. But in my case, I need all the Work Items, so I keep the defaults.

Note: Because I’m migrating from an on-prem TFS 2012.3 server to TFService, both using the Microsoft Visual Studio Scrum Process Template, I do not need further customization related to the Work Item Mapping. If you for example use the Agile Process Template, and you want to migrate to the Scrum Process Template, you can define some mappings like a User Story needs to be a Product Backlog Item. You can change all this if you click on the ‘Custom Settings – Edit XML‘.

One interesting thing to talk about is the user mapping. The on-prem  TFS server uses Active Directory and will display your full name. On the other hand, TFService uses your LiveId, so the system needs to have a mapping between your AD and the LiveId. You can manage this using the XML. Click on ‘Custom Settings – Edit XML’. And merge the following:

   <FieldMap name="FieldMap">
		   <MappedField LeftName="System.AssignedTo"
						MapFromSide="Left" valueMap="UserMap" />
	<ValueMap name="UserMap">
		<Value LeftValue="Alexander Vanwynsberghe"
			   RightValue="alexander@outlook.com" />

What this will do is use a FieldMap and a UserMap, telling the Integration Tools to map the AssignedTo value using the UserMap containing the mapping from AD to LiveId. All you have to do now is clicking on ‘Save To Database‘. This will save your configuration to the Integration Tools database.


That’s is, ready to go! Click on start and hope/pray that you do not have conflicts, and wait till the Migration is done! Note that it can take a while (4+ hours in my case) to migrate just one Team Project. But hey, it works! Note that in case of a conflict, the migration will stop! You have to resolve the conflict before the migration can continue.


Good luck with your migration!

Written by
Alexander Vanwynsberghe
Join the discussion

  • Dear Alexander, any problems migrating to TFS in the cloud/ Visual Studio Online using the ALM Rangers Kanban process template? I heard there were some limitations with customized WITs but I am not sure that is still the case.


Alexander Vanwynsberghe

Belgium-based entrepreneur. Into technology, innovation and a bit of cycling and running too. Evangelist for everything related to smart-tech.