How-to: Migrating Plans and Suites

This guide explains how to migrate Test Plans and Suites in Azure DevOps, including handling Shared Steps and Shared Parameters, and rebuilding Test Plans and Suites.

Last updated: June 25, 2025 | Edit this page | Discuss this page

Migrating Plans and Suites is quite convoluted since Shared Steps, which we need to map, can’t have a custom field.

  1. Migrate Basic Work Items
  2. Migrate Test Cases with their Shared Steps and Shared Parameter
  3. Migrate Test Variables & Test Configurations
  4. Rebuild Test Plans & Test Suites

WARNING: The configs below are for illustration and were correct as of the version number in the Version field.

top

1. Migrate Basic Work Items

This will migrate all of the work items, while also populating IntegrationBuild. Ensure that you have a Field Map that will copy ReflectedWorkItemId to Microsoft.VSTS.Build.IntegrationBuild.

The important bits:

  • Target ReflectedWorkItemIdField is your main Custom field.
  • Field map copies the ReflectedWorkItemId to Microsoft.VSTS.Build.IntegrationBuild
  • Exclude all test based work items from the query
{
  "Serilog": {
    "MinimumLevel": "Information"
  },
  "MigrationTools": {
    "Version": "16.0",
    "Endpoints": {
      "Source": {
        "EndpointType": "TfsTeamProjectEndpoint",
        "Collection": "https://dev.azure.com/nkdagility-preview/",
        "Project": "migrationSource1",
        "Authentication": {
          "AuthenticationMode": "AccessToken",
          "AccessToken": "** removed as a secret ***"
        }
      },
      "Target": {
        "EndpointType": "TfsTeamProjectEndpoint",
        "Collection": "https://dev.azure.com/nkdagility-preview/",
        "Project": "migrationTest5",
        "Authentication": {
          "AuthenticationMode": "AccessToken",
          "AccessToken": "** removed as a secret ***"
        },
        "ReflectedWorkItemIdField": "Custom.ReflectedWorkItemId"
      }
    },
    "Processors": [
      {
        "ProcessorType": "TfsWorkItemMigrationProcessor",
        "Enabled": false,
        "UpdateCreatedDate": false,
        "WIQLQuery": "SELECT [System.Id] FROM WorkItems WHERE [System.TeamProject] = @TeamProject AND [System.WorkItemType] NOT IN ('Test Case', 'Test Suite', 'Test Plan','Shared Steps','Shared Parameter','Feedback Request') ORDER BY [System.ChangedDate] desc"
      }
    ],
    "CommonTools": {
      "FieldMappingTool": {
        "Enabled": true,
        "FieldMaps": [
          {
            "FieldMapType": "FieldToFieldMap",
            "sourceField": "Custom.ReflectedWorkItemId",
            "targetField": "Microsoft.VSTS.Build.IntegrationBuild",
            "defaultValue": "",
            "ApplyTo": ["*"]
          }
        ]
      }
    }
  }
}
top

2. Migrate Test Cases with their Shared Steps and Shared Parameter

This will migrate Test Cases while fixing the links to the Shared bits that can’t be customised. This will use the Microsoft.VSTS.Build.IntegrationBuild to wire everything up as needed. It will also copy the Microsoft.VSTS.Build.IntegrationBuild to ReflectedWorkItemId for Test Cases so that we can also use them with work items.

The important bits:

  • Target ReflectedWorkItemIdField is a common field that is available on the non-customisable work items
  • Field Map copies Microsoft.VSTS.Build.IntegrationBuild to ReflectedWorkItemId for Test Cases only
  • The query includes only the Test items that we can migrate as work items (No Suites or Plans)
{
  "Serilog": {
    "MinimumLevel": "Information"
  },
  "MigrationTools": {
    "Version": "16.0",
    "Endpoints": {
      "Source": {
        "EndpointType": "TfsTeamProjectEndpoint",
        "Collection": "https://dev.azure.com/nkdagility-preview/",
        "Project": "migrationSource1",
        "Authentication": {
          "AuthenticationMode": "AccessToken",
          "AccessToken": "** removed as a secret ***"
        }
      },
      "Target": {
        "EndpointType": "TfsTeamProjectEndpoint",
        "Collection": "https://dev.azure.com/nkdagility-preview/",
        "Project": "migrationTest5",
        "Authentication": {
          "AuthenticationMode": "AccessToken",
          "AccessToken": "** removed as a secret ***"
        },
        "ReflectedWorkItemIdField": "Microsoft.VSTS.Build.IntegrationBuild"
      }
    },
    "Processors": [
      {
        "ProcessorType": "TfsWorkItemMigrationProcessor",
        "Enabled": true,
        "WIQLQuery": "SELECT [System.Id] FROM WorkItems WHERE [System.TeamProject] = @TeamProject AND [System.WorkItemType] IN ('Test Case','Shared Steps','Shared Parameter') ORDER BY [System.ChangedDate] desc"
      }
    ]
  }
}
top

3. Migrate Test Variables & Test Configurations

These are pre-requisites for rebuilding the Plans and Suites.

The important bits:

  • Processors for Test Variables & Test Configurations
{
  "Serilog": {
    "MinimumLevel": "Information"
  },
  "MigrationTools": {
    "Version": "16.0",
    "Endpoints": {
      "Source": {
        "EndpointType": "TfsTeamProjectEndpoint",
        "Collection": "https://dev.azure.com/nkdagility-preview/",
        "Project": "migrationSource1",
        "Authentication": {
          "AuthenticationMode": "AccessToken",
          "AccessToken": "** removed as a secret ***"
        }
      },
      "Target": {
        "EndpointType": "TfsTeamProjectEndpoint",
        "Collection": "https://dev.azure.com/nkdagility-preview/",
        "Project": "migrationTest5",
        "Authentication": {
          "AuthenticationMode": "AccessToken",
          "AccessToken": "** removed as a secret ***"
        },
        "ReflectedWorkItemIdField": "Custom.ReflectedWorkItemId"
      }
    },
    "Processors": [
      {
        "ProcessorType": "TfsTestVariablesMigrationProcessor",
        "Enabled": true,
        "Processor": "TestVariablesMigrationContext"
      },
      {
        "ProcessorType": "TfsTestConfigurationsMigrationProcessor",
        "Enabled": true
      }
    ]
  }
}
top

4. Rebuild Test Plans & Test Suites

This will rebuild the Plans and Suites and wire up all of the Test Cases.

note: Runs are not migrated.

The important bits:

  • Processors for TestPlansAndSuitesMigrationConfig
{
  "Serilog": {
    "MinimumLevel": "Information"
  },
  "MigrationTools": {
    "Version": "16.0",
    "Endpoints": {
      "Source": {
        "EndpointType": "TfsTeamProjectEndpoint",
        "Collection": "https://dev.azure.com/nkdagility-preview/",
        "Project": "migrationSource1",
       "Authentication": {
          "AuthenticationMode": "AccessToken",
          "AccessToken": "ouiasdhusahfkahfksdhksdhvksbdlsdvnlsdvsld"
        }
      },
      "Target": {
        "EndpointType": "TfsTeamProjectEndpoint",
        "Collection": "https://dev.azure.com/nkdagility-preview/",
        "Project": "migrationTest5",
        "ReflectedWorkItemIdField": "Custom.ReflectedWorkItemId",
        "Authentication": {
          "AuthenticationMode": "AccessToken",
          "AccessToken": "** removed as a secret ***"
        }
      }
    },
    "Processors": [
      {
        "ProcessorType": "** removed as a secret ***",
        "Enabled": true,
        "OnlyElementsWithTag": "",
        "TestPlanQuery": null,
        "RemoveAllLinks": false,
        "MigrationDelay": 0,
        "RemoveInvalidTestSuiteLinks": false,
        "FilterCompleted": false
      }
    ]
  }
}
Previous How-To: Creating area and iteration maps
Next How-To: User Mappings
Project Information
Azure DevOps Marketplace
Visual Studio Marketplace Stars View Extension
YouTube Channel
Youtube Subscribers Youtube Views
Maintainer

Created and maintained by Martin Hinshelwood of nkdagility.com

Documentation Versions
Production Azure DevOps Migration Tools Release Version
Preview Azure DevOps Migration Tools Preview Version
Getting Support
Community Support
Questions & Discussions

The first place to look for usage, configuration, and general help.

Commercial Support

We provide training, ad-hoc support, and full service migrations through our professional services.

Azure DevOps Migration Services
Documentation