We are looking into using the Microsoft’s hosted Team Foundation Service, and the first question that always comes up is “I have an existing TFS project, how do I get my source (and work items) up there as a starting point?”  So I decided to look into it, and found the TFS Integration Platform written by the ALM Rangers at Microsoft.  MSDN Magazine has a good article to use for background and to get you started, but I had to do some custom tweaks to get mine to work.

First off – let’s set the goal:  migrate source code (including history) and Work Items from an on-premise TFS to the Microsoft hosted TFS.  I’m starting with a brand new Team Project in the hosted TFS, so if you merge code into an existing project or branch, your mileage may vary.

Second – we use a custom process template (modified from SCRUM) here at IK, and we are going to use the Agile process template online, so that adds a little complexity to the migration, as I have to map fields from the local process template to the hosted one.

Preparation

Create a work item query in the source TFS that includes the work items you want to migrate.  In my case, I have SPRINT types in the local TFS, but those don’t exist in the destination Agile process template, so my query includes only Product Backlog Items (that we’ll map to User Stories), Tasks, and Bugs.

Integration Tool

Fire up the tool, and click Create New. Select the “Team Foundation Server\VersionControlAndWorkItemTracking.xml” template.  This gives you all the configuration settings you need for migrating both source control and work items.

Configure the source (left side) and destination (right side) connection information for each of Version Control and Work Item Tracking.  I used VS 11 (TFS 2012) for both my local and hosted TFS connections.

Source Control

By default, the source control session will migrate from the root of the source tree in the local repository to the root of the source tree in the remote one.  This caused a bunch of conflict errors for me, since even the newly created Team Project in the hosted TFS has some build template files in the BuildProcessTemplates folder.  Since the source and the destination both have the same files, there are conflicts during the merge.  You can work around them by specifying which version to use, but I avoid the hassle by filtering the source that’s migrated to a sibling tree that does not include the BuildProcessTemplates folder.  The tool seems to provide a way to cloak a directory such as the BuildProcessTemplates folder, but I could not get that to work.

So for both source and destination, I choose the source tree one level below the root.  Click the “…” button next to each side of the PATHS section to point to the correct source directory.  My config now looks like this:

Work Items

Now we’re going to limit the migration to only the work items that are returned by the query we created above.  Click the “…” button next to the edit box in the “Queries” section and navigate to the query, mine is called “Migrate these Work Items” (again, it only includes Product Backlog Items, Tasks, and Bugs; not Sprints). 

Notice when you come back from choosing the query, the actual CONTENT of the query is inserted into the edit box, instead of just a reference to the query.  I thought that was kind of interesting.

Custom Mapping

Finally, as I described above, I have to do some custom mappings to get the work items from our custom SCRUM template to the hosted TFS Agile template (we want to use some fields that are in Agile and not in Scrum in the hosted TFS, and process templates can’t be customized yet). 

Click the “Custom Settings” button, which gives you a dialog with the settings XML.  I chose to edit the XML in VS and then just paste it in here.  Here’s the top section of what mine looks like:

Here is a zip that contains the settings I used.  You can use it as a starting point and then adjust as needed.  There is a section at the bottom that attempts to map users from the source to destination TFS systems, but I couldn’t get that to work either. 

That’s it – SAVE and START.  Watch the progress, and check for any conflicts. If you get some, you’ll have to resolve each issue independently.  It looks like the tool does a bunch of analysis and validation first, and will only proceed to the actual migration when there are no conflicts.   

Results

When it’s done, I go look at the source in the destination hosted TFS, and see the version history!  (Notice how the check-ins come through as the user that was running the tool, with some extra text to show when/how it was done.)

Hope that helps.