TFS 2017 Migration To VSTS with VSTS Sync Migrator

Introduction

Step 1: Getting Environment Ready

Step 2: Preparing TFS

Step 3: Preparing VSTS

Step 4: Preparing JSON File

Step 5: Migrate Work Iterations

Step 6: Migrating Work Items

Step 7: Migrating Links between Work Items

Step 8: Migrating Attachments

Conclusion


 

Introduction

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

  1. TFS Process Template Editor extension for Visual Studio installed.
  2. Open The Process Editor Extension in Visual Studio
  3. Download & Install VSTS Sync Migrator.
  4. Open Command Prompt or PowerShell
  5. Navigate with CMD or PS to a new folder (Recommended)
  6. Run the command vstssyncmigrator init to create a default configuration
  7. 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

VSTS_Sync_Mig_Update_TFS_Fields

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.

VSTS_Sync_Mig_Update_TFS_Fields_2

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

VSTS_Settings_Process

3. Open Your Inherited Process Settings

Open_Inh_Process

4. For Each Work Item Type, Open it and repeat the following steps

VSTS_Edit_WIT

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

VSTS_Add_Field_To_WIT

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.

Check_New_Field

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 MyInheritedProcessName.ReflectedWorkItemId

4. Put the same value for step 3 in the targetField Option.

JSON_1

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).

JSON_2

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.

JSON_3

Step 5: Migrate Work Iterations

The First Thing we should migrate is the work iterations, this is known in the file with Object Type

VSTSSyncMigrator.Engine.Configuration.Processing.NodeStructureMigrationConfig

As we can see on VSTS, we have no iterations (Except the parent node):

Empty_Iteration

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.

1_Node_Structure_Migration

3. Run the following command vstssyncmigrator.exe execute –config vstsbulkeditor.json

2_CMD_Node_Start

 

4. This might take a minute or less, Once finished you’ll see something like this:

3_CMD_Node_Done

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.

Empty_Backlog

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
(VSTSSyncMigrator.Engine.Configuration.Processing.WorkItemRevisionReplayMigrationConfig)

5. I’ll choose migration with history, so we’ll set the Enabled flag for it to be true.

JSON_Migrate_Work_Items

 

6. Open the command prompt again, and run the same command again
(vstssyncmigrator.exe execute –config vstsbulkeditor.json).

Run_WIT_Migration

7. The last step might take sometime depending on how many work items are there, in my case it took around 17 minutes .

CMD_Mig_WIT_Done

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.

Full_Backlog

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.

No_Count_For_Links

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

JSON_Migrate_Links

 

4. Open the command prompt again, and run the same command again
(vstssyncmigrator.exe execute –config vstsbulkeditor.json)

5. This could take few minutes.

CMD_Mig_Links_Done

6. If we check VSTS again, we’ll see that links have been migrated

VSTS_After_Migration_Links

Step 8: Migrating Attachments

Now attachments for Work Items is the only remaining thing, as we can see the attachments count is zero.

No_Attachment

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

  1. The first one is VSTSSyncMigrator.Engine.Configuration.Processing.AttachmentExportMigrationConfig
  2. And the second one is VSTSSyncMigrator.Engine.Configuration.Processing.AttachmentExportMigrationConfig

Both of them should be set to true

JSON_Attachments

3. Open the command prompt again, and run the same command again
(vstssyncmigrator.exe execute –config vstsbulkeditor.json).

CMD_Mig_Att

4. This might take few minutes.

CMD_Mig_Att_Done

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_Att_Mig_Done

 

Conclusion

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.

 

Share This: