Today, we will look at a simple problem of migrating work items from TFS Server (Also called as Azure DevOps Server for later version of TFS Servers) into Azure DevOps Services.
Objective of migration would also be to have the below objectives met:
All Work Items are migrated.
Relationships between Work Items like Parent / Child etc are retained
History of work items w.r.t the users comments, discussion field and all other fields would be retained (and/or mapped properly).
Queries, Test plans, Test Suites etc. would all be copied as well.
Prior to making the migration, ensure that you have
“Project Administrator Access on Azure DevOps Services (destination) project”,
“Project Administrator Access on Source Project”
PAT token created in the Destination project (more on this will be provided in the below article)
Destination Project should have the ReflectedWorkItemID field for all Work Item types (more on this will be provided in the below article)
Install chocolatey tool by following the below set of commands in your Windows 10 OS (Google for installing chocolatey for other OSs if you are using any other OSs):
Once chocolatey is installed, run the below command after changing the directory of your choice in the command line (say C:\Tools\) to download Azure DevOps Migration tool directly into your system:
choco install vsts-sync-migratorRunning this would create a folder structure like : C:\tools\VSTSSyncMigration which would have migration.exe file. Checking the version of my migrator.exe suggests that I have version 8.8 of VSTS Sync migrator installed. (It might be different by the time you would have installed the vsts sync migrator)
Once the installation is done, we have to create/initialize the configuration file by running the below command:
cd C:\tools\VSTSSyncMigration
.\migration.exe initThe configuration file created by running the above command will create different configuration.json file for different versions of vsts-sync-migrator (So, the configuration.json created for you would differ from the one I am showcasing. But no worries, it all works the same way optimistically speaking)
In this generated file, we are required to make some modifications as per the intent of our migration. In my case, I am planning to move work items from Agile SDLC in TFS to Agile SDLC in Azure DevOps Services. And, the configuration file looks like the one attached for your reference.
Here, I have masked a part of the PersonalAccessToken (PAT) by replacing some part of the token with x’s. However, you can create one by following the below article against your destination project.
From the configuration file, you can see that I am performing the migration from :
Source Project Collection: https://us-eytfs.ey.net/tfs/ATMBMC/
Source Project : ADV.GRaCEY
To the destination project https://eysbp.visualstudio.com/ (Destination project collection), Destination Project Name: ADV – EYCompass
You can correlate from the mapping shown above and the configuration file entries for Source and Target nodes as to what these field values should be for your source / destination projects.
Now, please note the ReflectedWorkItemId field here. This field can be any field in the destination project (which is being unused for any purposes at all). However, it would be better off if there is a special field called ‘ReflectedWorkItemId’ in the destination.
So, how do you know if all your work item types have this ReflectedWorkItemId field against them ?
You can know if they exist by checking it under the target DevOps services project by navigating like below:
Go to ‘Organization Settings’ -> Your project -> ‘Processes’ (or browse to: https://eysbp.visualstudio.com/_settings/process ) There, under processes, chose all Work Item types (Like I selected Bug below) and I see ReflectedWorkItemId (If I don’t see it, then I would add it to the process which my project is linked to so that all Bugs will have this field against them.)
Similarly, we need to ensure that all Work Item Types like User stories, Task, Feature, Epic etc. and have ReflectedWorkItemId field available against them.
Also, we can know if the field ‘ReflectedWorkItemId’ is writable field by checking the below link (replace ADV – EYCompass with your project name):
[Note: The above link will also help know the fully qualified field names that we use as a filter (I had used System.CreatedDate as a filter for migrating only work items created after a particular date like below)]
FieldToFieldMap is used for mapping from one source field’s value to another. In my case, since the migration is from Agile to Agile SDLC, I didn’t have any issues with explicitly configuring the FieldToFieldMap’s
Once all the required state changes are provided in the configuration file, then, we run the below command to initiate the Work Item migration. We can do it in one command prompt with ne config file. OR, we can create multiple config files with different range of Created Date (in order to ensure parallel and faster execution). I prefer the latter as we had tons of work items required for migration.
Command to run the actual migration once the config file is setup:
cd C:\tools\VSTSSyncMigration
.\migration.exe execute -c .\configuration.jsonOnce this is run, you would be on auto pilot to complete the migration process. Happy migration 😊
[PFB the configuration.json file which I used in 8.8 version for migration. Tweaking files here and there and following up on https://mohamedradwan.com/2017/09/15/tfs-2017-migration-to-vsts-with-vsts-sync-migrator/ should help adequately.]
Comments