In my previous post I’ve described the migration between TFS and VSTS, with usage of TFS Integration Platform. As described in that post, the tool is pretty simple and strait forward to use, but it doesn’t supports the migration of all artefacts, such as links between the work items. Besides that, I think it’s worth mentioning again, that this migration tool is deprecated. If your migration demands a high fidelity than this tool would not be appropriate.
For such cases, demanding the high fidelity, VSTS Sync Migrator is appropriate solution. This tool is a very powerful and nice tool developed by Martin Hinshelwood who is a fellow ALM MVP. The tool strength comes from its coverage for all migration options.
Migration with VSTS Sync Migration Tool is a bit complicated, however it’s a powerful option as we don’t have limitations for migrating links, attachments or work items.
Step 1: Getting Environment Ready
Before starting the migration, make sure to have
- TFS Process Template Editor extension for Visual Studio installed.
- Open The Process Editor Extension in Visual Studio
- Download & Install VSTS Sync Migrator.
- Open Command Prompt or PowerShell
- Navigate with CMD or PS to a new folder (Recommended)
- Run the command
vstssyncmigrator initto create a default configuration
- Open “vstsbulkeditor.json” file from the same directory.
Step 2: Preparing TFS
For Migration to succeed, we need to have an additional field in both TFS & VSTS for tracking purpose (This is essential for the tool to be able to link work items to each other).
1. To do that, Open Visual Studio
2. Open the Tools Menu
3. Open Process Editor Menu
4. Open Work Item Types
5. Click Open WIT From Server
For each of the Work Item Types in your Project, do the following
6. Click On New
7. Set the Field Name to ReflectedWorkItemId
8. Make sure it’s of type String
9. Set the Reference Name to TfsMigrationTool.ReflectedWorkItemId
10. Click OK
11. The Field is now added.
Important Note: Make sure to add the field to all Work Item Types.
Step 3: Preparing VSTS
We need also to modify Work Items in VSTS to match with TFS, so the Tool can complete the Migration Process
1. Open your VSTS Account Settings
2. Open Process Settings
3. Open Your Inherited Process Settings
4. For Each Work Item Type, Open it and repeat the following steps
5. Click Add New
6. In the New Field Dialog, Set the New Field name to be ReflectedWorkItemId
7. Make sure it’s of Type Text Single Line
8. Click Add Field
Make sure you have added the field to all Work Item Types, You can check Work Items (to make sure you have added the field) by Going to Your Inherited Process and check the work Item.
Step 4: Preparing JSON File
Do you remember the file we opened in the step 2.1.7 ? Let’s get back to this file to adjust few things before starting the migration
1. In the source we add information for the old TFS, we will add the URL for the old TFS under the Collection option and the old project name under the Name Option.
2. In the target we add information for VSTS, we will add the URL for the VSTS under the Collection option and the VSTS project name under the Name option.
3. In the ReflectedWorkItemIdFieldName option, but the Name of your inherited Process followed by a period and “ReflectedWorkItemId”, the should look finally like this
4. Put the same value for step 3 in the targetField Option.
5. Optional: You can use the valueMapping to change states of work items being migrated, this can be helpful if you’re migrating between Scrum and Agile (or vice versa).
6. Optional, WorkItemTypeDefinition is used to map Work Item Names, this also should be used if you’re migrating between Scrum and Agile.
7. Processors is the control units for migration, each processor controls migration of a specific part of TFS. If you don’t have any processor enabled, the tool won’t work at all.
8. Each processor has an ObjectType, which is the name for Object being migrated.
9. Each processor has an Enabled flag, which is either true or false, if it’s enabled (true) then this processor will be executed during migration.
Step 5: Migrate Work Iterations
The First Thing we should migrate is the work iterations, this is known in the file with Object Type
As we can see on VSTS, we have no iterations (Except the parent node):
2. Now To Migrate Iterations and its structure, Let’s get back to the JSON File, Set the Enabled flag for the Object VSTSSyncMigrator.Engine.Configuration.Processing.NodeStructureMigrationConfig to be true, otherwise the tool won’t run this part.
3. Run the following command vstssyncmigrator.exe execute –config vstsbulkeditor.json
4. This might take a minute or less, Once finished you’ll see something like this:
Step 6: Migrating Work Items
Now Let’s move to the Migrating The Work Items itself, Here the VSTS before migrating any work items.
So here is a query on the new VSTS (Lists all items in tree view) which shows that we have nothing yet.
Now Lets start Migrating Work Items,
1. Open the file again, make sure to set the Object VSTSSyncMigrator.Engine.Configuration.Processing.NodeStructureMigrationConfig to be False, This is very important.
2. We have Two Options for Migrating Work Items, As described below
3. The First Option is to Migrate work items with recent state, which means that the history of work items will be lost (VSTSSyncMigrator.Engine.Configuration.Processing.WorkItemMigrationConfig)
4. The Second Option is to Migrate work items with its history
5. I’ll choose migration with history, so we’ll set the Enabled flag for it to be true.
6. Open the command prompt again, and run the same command again
(vstssyncmigrator.exe execute –config vstsbulkeditor.json).
7. The last step might take sometime depending on how many work items are there, in my case it took around 17 minutes .
Here is how VSTS Looks after Migration, Remember that so far we did only migrate Work Items, but with no links between them and with no Attachments.
Step 7: Migrating Links between Work Items
Now is the time to Migrate the links between work items, I added one more column to demonstrate that, as we can see there is links between work items count is zero.
So let’s get back to file,
1. Open the file again, make sure to set the Object VSTSSyncMigrator.Engine.Configuration.Processing.WorkItemRevisionReplayMigrationConfig to be False, This is very important.
2. Find the Object VSTSSyncMigrator.Engine.Configuration.Processing.LinkMigrationConfig
3. Set the Enabled flag for this object to be true
4. Open the command prompt again, and run the same command again
(vstssyncmigrator.exe execute –config vstsbulkeditor.json)
5. This could take few minutes.
6. If we check VSTS again, we’ll see that links have been migrated
Step 8: Migrating Attachments
Now attachments for Work Items is the only remaining thing, as we can see the attachments count is zero.
Let’s get back to the file
1. Open the file again, make sure to set the Object VSTSSyncMigrator.Engine.Configuration.Processing.LinkMigrationConfig to be False, This is very important.
2. For Migrating attachments, we need two options to be enabled (true), not only one, the options are
- The first one is VSTSSyncMigrator.Engine.Configuration.Processing.AttachmentExportMigrationConfig
- And the second one is VSTSSyncMigrator.Engine.Configuration.Processing.AttachmentExportMigrationConfig
Both of them should be set to true
3. Open the command prompt again, and run the same command again
(vstssyncmigrator.exe execute –config vstsbulkeditor.json).
4. This might take few minutes.
5. Now Let’s check the Attachment Count IN VSTS Again.
6. And Finally, here is the Work Items in the VSTS, with Attachments migrated
VSTS Sync Migrator is a very powerful tool Developed by Martin Hinshelwood. The Tool allows migrating everything between TFS and VSTS, including Work Items, Iterations, Attachments, Links between work Items and even more options can be found in the official documentation.
The tool still requires a bit of experience and understanding for both TFS and VSTS, but it’s really covering migration of all project artefacts, which adds up a big value to the tool.