Tutorial: Get started with the Azure DevOps Migration Tools

If you want to perform a bulk edit or a migration then you need to start here. This tool has been tested on updating from 100 to 250,000 work items by its users.

Watch the Video Overview to get started in 30 minutes. This tool is complicated and it’s not always easy to discover what you need to do.

Prerequisits

1. Install the tools using your prefered method.
2. Check that you have the required Permissions to run the tools.
3. Get to grips with the Configuration to understand how to configure the tool. (you can skip this for now and come back to it later)

Validation Process

Before you begin migration, review the Validation Process documentation to understand how the tools automatically check your configuration and data for common issues. This can save you significant time and help avoid common migration errors.

Getting Started

This is going to be a crash course and I really recommend watching What can go wrong and what can go right with a migration via Azure DevOps and then Basic Work Item Migration with the Azure DevOps Migration Tools before you get started! This will prep you for the journey ahead.

New to migration tools? Try our Interactive Configuration Wizard to build your configuration step-by-step with guided explanations!

1. Create a default configuration file

1. Open your Windows Terminal in your chosen working folder
2. Run devopsmigration init --options Basic to create a default configuration
3. Open configuration.json from the current directory

You can now customize the configuration depending on what you need to do. However, a basic config that you can use to migrate from one team project to another with the same process will likely look something like:

{
  "Serilog": {
    "MinimumLevel": "Information"
  },
  "MigrationTools": {
    "Version": "16.0",
    "Endpoints": {
      "Source": {
        "EndpointType": "TfsTeamProjectEndpoint",
        "Collection": "https://dev.azure.com/nkdagility-preview/",
        "Project": "migrationSource1",
        "Authentication": {
          "AuthenticationMode": "AccessToken",
          "AccessToken": "**redacted**"
        }
      },
      "Target": {
        "EndpointType": "TfsTeamProjectEndpoint",
        "Collection": "https://dev.azure.com/nkdagility-preview/",
        "Project": "migrationTest5",

        "Authentication": {
          "AuthenticationMode": "AccessToken",
          "AccessToken": "**redacted**"
        },
        "ReflectedWorkItemIdField": "Custom.ReflectedWorkItemId"
      }
    },
    "CommonTools": {},
    "Processors": [
      {
        "ProcessorType": "TfsWorkItemMigrationProcessor",
        "Enabled": true,
        "WIQLQuery": "SELECT [System.Id] FROM WorkItems WHERE [System.TeamProject] = @TeamProject AND [System.WorkItemType] NOT IN ('Test Suite', 'Test Plan','Shared Steps','Shared Parameter','Feedback Request') ORDER BY [System.ChangedDate] desc"
      }
    ]
  }
}

The default TfsWorkItemMigrationProcesor processor will perform the following operations:

• Migrate iterations and sprints
• Attachments
• Links including source code. Optionally clone the repositories before starting the migration to have links maintained on the initial pass.

How to execute configuration.json with minimal adjustments

Remember to add custom field ‘ReflectedWorkItemId’ to only the target team project before starting migration!

[NOTE!] In older versions of the tool we updated the Source work items with a link back to the Target to make migration easier. This has been removed and replaced with the FilterWorkItemsThatAlreadyExistInTarget option instead. You do not need to add the reflected work item ID custom field to the Source environment.

1. Adjust the value of the Collection attribute for Source and Target

2. Adjust the value of the Project attribute for Source and Target

3. Set the AuthenticationMode (Prompt or AccessToken) for Source and Target

   If you set Authentication mode to AccessToken, enter a valid PAT as value for the PersonalAccessToken attribute, or set the PersonalAccessTokenVariableName to the name of an environment variable containing your PAT.

4. Adjust the value of the ReflectedWorkItemIdField attribute (field name of the migration tracking field) for Source and Target

   For example: TfsMigrationTool.ReflectedWorkItemId for TFS, ReflectedWorkItemId for VSTS, or Custom.ReflectedWorkItemId for Azure DevOps

5. Enable the WorkItemMigrationConfig processor by setting Enabled to true

6. [OPTIONAL] Modify the WIQLQueryBit to migrate only the work items you want. The default WIQL will migrate all open work items and revisions excluding test suites and plans

7. Adjust the NodeBasePaths or leave empty to migrate all nodes

8. From your working folder run devopsmigration execute --config .\configuration.json

Common Issue: Work Item Type Validation Failures

⚠️ IMPORTANT: The migration tools include automatic validation that runs before migration starts and can cause your migration to fail if source and target systems have different work item types or fields.

The TfsWorkItemTypeValidatorTool automatically validates that:

• All source work item types exist in the target system (or have mappings configured)
• Required fields exist in target work item types
• Field types are compatible between source and target
• The ReflectedWorkItemId field exists in target work item types

If validation fails, the migration will stop immediately with detailed error messages. Here’s how to resolve common validation issues:

Missing Work Item Types:

Work item type 'Risk' does not exist in target system.

• Solution 1: Create the missing work item type in your target system
• Solution 2: Configure a work item type mapping to map ‘Risk’ to an existing type like ‘Issue’
• Solution 3: Exclude the work item type from your migration query

Missing ReflectedWorkItemId Field:

'User Story' does not contain reflected work item ID field 'Custom.ReflectedWorkItemId'.

• Solution: Add the custom field to ALL work item types in your target project (see ReflectedWorkItemId setup )

Missing Custom Fields:

Missing field 'Microsoft.VSTS.Common.CustomField' in 'User Story'.

• Solution 1: Add the missing field to the target work item type
• Solution 2: Configure field mapping to map to an existing field
• Solution 3: Exclude the field from validation if it’s not needed

For a complete overview of the validation process—including both pre-migration and pre-data-load validation steps—see the Validation Process documentation .

For detailed troubleshooting and configuration options, see the TfsWorkItemTypeValidatorTool documentation .

Remember: If you want a processor to run, its Enabled attribute must be set to true.

Refer to the Reference Guide for more details.

Other Configuration Options

When running devopsmigration init you can also pass --options with one of the following:

• Full -
• WorkItemTracking -
• Fullv2 -
• WorkItemTrackingv2 -