Rajeev Pentyala – Microsoft Power Platform

In this blog post, I am going to explain how I was able to migrate Azure DevOps work items, including Area Path, Iterations, Links, Attachments, etc., using the open source Azure DevOps Migration Tools.

Overview of ‘Azure DevOps Migration Tools’:

• The ‘Azure DevOps Migration Tools’ allow you to migrate Teams, Backlogs, Tasks, Test Cases, and Plans & Suites from one Project to another in Azure DevOps/TFS, both within the same Organization and between Organizations.
• The ‘Azure DevOps Migration Tools’ is an open-source C# console project available on GitHub.

What can you do with this tool?

• Migrate Work Items, TestPlans & Suits, Teams, Shared Queries, Pipelines,  Processes from one Team Project to another.
• Migrate Work Items, TestPlans & Suits, Teams, Shared Queries, Pipelines, & Processes from one Organization to another.
• Bulk edit of Work Items across an entire Project.

Now that we have an overview of Azure DevOps Migration Tools, let me demonstrate how we can use this tool with a simple scenario.

Scenario:

• I have an Azure DevOps organization with two Projects. , named ‘Source Project’ and ‘Target Project’ for simplicity.

• My ‘Source Project’ has Areas and Iterations defined as below.

• The ‘Source Project’ has work items with links to other work items and also includes attachments.

• As for the ‘Target Project,’ where we will be migrating items to, it’s a brand new project without any work items, areas, or iterations.

In summary, we will migrate the work items with links, comments, attachments, and areas and iterations from ‘Source Project’ to ‘Target Project’ using the ‘Azure DevOps Migration Tools.’

Disclaimer:

‘Azure DevOps Migration Tools’ can be used by installing as winget package in to your machine, which showed in this Video Overview.

But what I am going to show you is a simpler way of downloading the ‘Azure DevOps Migration Tools’ build directly from GitHub Release and running it locally on my machine..

Now that we understand the scenario, let’s get started with the prerequisites and the migration process.

Pre-requisites for using ‘Azure DevOps Migration Tools’:

Create a Azure DevOps Personal Access Token (PAT)

• We need to generate a Azure DevOps PAT token with ‘Full Access’, as an alternate password to authenticate into your Azure DevOps organization from the ‘Azure DevOps Migration Tools’.
• Sign in to your organization (https://dev.azure.com/{yourorganization}).
• From your home page, open user settings and select Personal access tokens.
• Select + New Token.
• Name your token with ‘Full access’ scope as shown below and click on ‘Create’.

• When you’re done, copy the token and store it in a secure location. For your security, it doesn’t display again.

Add a custom field to ‘Target Project’ work items:

To migrate the work items, ‘Azure DevOps Migration Tools’ tool, requires a new ‘Custom Field‘ to be added to all the Work Item types that we need to migrate.

• Select the ‘Target Project’
  • Note : Select your destination project where you want to migrate. In my case, since my destination project is named ‘Target Project,’ I have chosen this.
• Go to Project Settings > Overview > Process > Click on your process.
  • Note : You might be having a different process name in your case.

• You will be redirected to the Process screen, as shown below.

• Double click on any of the work item type, and click on ‘New field’. I’ve chosen ‘Feature’ work item type.

• Provide the ‘Name’ as ReflectedWorkItemId and click on ‘Add field’.

• Now you will see the ReflectedWorkItemId field added to the ‘Feature’ work item type.

• We have to add the ReflectedWorkItemId field to the other work item type’s that we are planning to migrate from the source DevOps project.
• We don’t need to create ReflectedWorkItemId field again; we just need to add the already created ReflectedWorkItemId to the other work item types.
• For example, to add the ReflectedWorkItemId field to the ‘Bug’, open the ‘Bug’ work item type and click on ‘New field’.

• From the ‘Use an existing field’ select the ReflectedWorkItemId and click on ‘Add field’.

• Repeat the above step for all work item types you are planning to migrate.

Download the ‘Azure DevOps Migration Tools’ build :

• Open the ‘Azure DevOps Migration Tools’ GitHub project.
• Open the releases page by navigating to the azure-devops-migration-tools/releases.
• Select the latest release and download the ‘MigrationTolls-x.x.x.zip‘ folder as highlighted below.

• Extract the MigrationTolls-x.x.x.zip folder to your local drive.

• We are good to start with migration.

Now that all prerequisites are fulfilled, let’s see how to start the migration process.

Steps to migrate the work items:

Following are the high level steps for migration:

• Generate the ‘Configuration file’.
• Update ‘Configuration file’ with your source and destination DevOps project details and authentication details.
• Trigger the migration process.

Generate the ‘Configuration file’:

• Open your Windows Terminal and point to the extracted MigrationTolls-x.x.x.zip folder.
• Run devopsmigration init command to create a configuration file as shown below.

• On successful command execution, a message is displayed as highlighted below, and a new ‘configuration.json’ file gets created.

• Open the ‘configuration.json’ file in editor as shown below.

• The ‘configuration.json’ file looks like the one below, with ‘Source’ and ‘Target’ nodes.

• Adjust the ‘Collection’ and ‘Project’ names with your DevOps project names in both ‘Source’ and ‘Target’ nodes.

• Set the AuthenticationMode to ‘AccessToken‘ for Source and Target and provide the PAT token details which we generated in pre-requisites step.

• Set the Enabled attribute to true

• That’s it. We are good to trigger the migration.

Trigger the migration process:

To trigger the work item migration process, we will be executing devopsmigration execute command by passing the ‘configuration.json’ file path as parameter.

• Execute the devopsmigration execute command.

devopsmigration execute --config D:\Practice\MigrationTools-14.4.6\configuration.json

• Once completed, you will get response as shown below.

• Confirm the migration of work items by navigating to the ‘Target Project’ and selecting Boards > Work items.
• Notice below that all work items successfully migrated from the ‘Source Project’ to the ‘Target Project’ along with Area and Iteration paths.

That’s it. I’ve explained the work item type migration between projects within the same Azure DevOps organization.

If you have to migrate the work items to a project in a different Azure DevOps organization, it’s the same set of steps to follow. Additionally, you would be creating a separate PAT token for both organizations.

Please refer the Azure DevOps Migration Tools documentation for more details.

🙂