Skip to content

Work Item Migration

Every now and then I’m asked to do a Work Item migration from one Azure DevOps organization (or project) to another and as it is not that rare case anymore, it is still surprisingly hard to do and there are few good reasons why.

Migrations Are Tricky

The most common problem with migration is that, the source data is not integrated. It has lots of special cases and edges that needs to be plane down during migration. Another common problem is that the result data, needs to be different from source. For example we don’t want to migrate old users, or we don’t want to bring all the test cases from old system into new one, so in migration the collecting of requirements is the number one job. I have created a list of questions that should be answered before any migration steps are planned.

Work Item Migration Questions

  1. Why and for who, we are doing the migration?
  2. What type of work items we should migrate?
  3. What is the amount of migrated work items?
  4. Do we need attachments from old projects?
  5. Are we going to migrate areas and iterations?
  6. Are the users in both system with same identifiers? Do we have an AD authentication?
  7. Are we going to bring the version history of work items?

Options

There are currently few good migration options to choose from. The level of requirements and how much time can be spend on migration defines the right option.

Good old Excel

We all love Excel right? It is the Swiss army knife of computer software and for no surprise it is also suitable for Work Item migrations. First we need to install the Excel plugin for Azure DevOps: https://docs.microsoft.com/en-us/azure/devops/boards/backlogs/office/bulk-add-modify-work-items-excel?view=azure-devops&tabs=agile-process. With this plugin we can fetch work items and even create/update them directly from the Excel.

After installation, create new Excel spreadsheet and connect into Azure DevOps project with the tools in the “Team” tab.

DevOps Tools in Excel

For source data (getting the migrated work items), I suggest doing a query to Azure DevOps, which applies the required filtering and ordering of work items. Query can be also used to define what kind of data (columns) is migrated.

After creating the connection and query, open another Excel and connect into target ADO project (that needs to be created first of course). Then just copy paste rows from source to target and click “publish” in target. Possible errors are reported directly into Excel and the faulty rows can be fixed manually (or by using the Excel’s normal script abilities). Publish command will send work items one-by-one, so if the migration stops in the third row, you should be able to see the first two work items in the ADO.

Downsides of Excel migration

Excel migration is easy, but it has few major downsides. First is that migrating comments is not possible. Excel migration also does not support attachments and images. Usually that is the show stopper for most of the migration projects, but if you really not need old images / comments or can view them from source project for migrated data, then the Excel approach is easy and fast.

Azure DevOps Migration Tools

ADO Migration Tools is a pro version of migration. It has ability to migrate attachments, work item history, comments, build relations between old and new system and even change the default values during the migration. However all this comes with a downside: Configuring the migration tool is really really hard.

Easiest way to install Migration Tools is to run 

choco upgrade vsts-sync-migrator

Here is a simple configuration that can be used with version 9.1 to migrate work items, areas and iterations from one project to another.

{
  "Version": "9.1",
  "TelemetryEnableTrace": false,
  "workaroundForQuerySOAPBugEnabled": false,
  "Source": {
    "Collection": "https://dev.azure.com/{your organization}",
    "Project": "{project name}",
    "ReflectedWorkItemIDFieldName": "TfsMigrationTool.ReflectedWorkItemId",
    "AllowCrossProjectLinking": false,
    "LanguageMaps": {
      "AreaPath": "Area",
      "IterationPath": "Iteration"
      }
  },
  "Target": {
    "Collection": "https://dev.azure.com/{your organization 2}",
    "Project": "{your project 2}",
    "ReflectedWorkItemIDFieldName": "ReflectedWorkItemId",
    "AllowCrossProjectLinking": false,
    "LanguageMaps": {
      "AreaPath": "Area",
      "IterationPath": "Iteration"
      }
  },
  "FieldMaps": [],
  "WorkItemTypeDefinition": {
  },
  "GitRepoMapping": null,
  "Processors": [
    {
      "ObjectType": "VstsSyncMigrator.Engine.Configuration.Processing.NodeStructuresMigrationConfig",
      "Enabled": true,
      "PrefixProjectToNodes": false
    },
    {
      "ObjectType": "VstsSyncMigrator.Engine.Configuration.Processing.WorkItemMigrationConfig",
      "ReplayRevisions": false,
      "PrefixProjectToNodes": false,
      "UpdateCreatedDate": true,
      "UpdateCreatedBy": true,
      "UpdateSourceReflectedId": false,
      "BuildFieldTable": false,
      "AppendMigrationToolSignatureFooter": false,
      "QueryBit": "AND  [Microsoft.VSTS.Common.ClosedDate] = '' AND [System.WorkItemType] NOT IN ('Test Suite', 'Test Plan')",
      "OrderBit": "[System.ChangedDate] desc",
      "Enabled": true,
      "LinkMigration": true,
      "AttachmentMigration": true,
      "AttachmentWorkingPath": "c:\\temp\\WorkItemAttachmentWorkingFolder\\",
      "FixHtmlAttachmentLinks": false,
      "WorkItemCreateRetryLimit": 5,
      "FilterWorkItemsThatAlreadyExistInTarget": true,
      "PauseAfterEachWorkItem": false
    }
  ]
}

To run the migration open up a console with administrator permissions and run following command in the directory where migration tool is installed:

.\migration.exe execute -c configuration.json

Tool will ask credentials for both projects (source and target) and then starts copying the work items. There are few things in configuration that I would like to raise up:

  • The target project has configuration “ReflectedWorkItemIDFieldName”: “ReflectedWorkItemId“. This means that you need to add ReflectedWorkItemId field to ALL migrated work item types. The data type for field is string (it is url into original work item). The field can be added in the process customization page. Add field as new field to first work item type and then use the “Existing field” option for other types. This field is added into target project.
  • ReplayRevisions is set to false. This means that migration tool will only add the latest changes and does not try to bring whole history.

During the migration the tool will add comment about migration into every new work item. The comment contains handy link to original work item.

Handy migration comment is added automatically.

Summary

If you are going to migrate work items and your need is simple: Only work items without comments and attachments. Then choose the Excel option. If you need more than plain work items with descriptions and topics. Use tool like Azure DevOps Migration Tools. Always remember to think about what is the minimum data that you are going to need in the new project. Don’t bring anything extra.

Migrations are difficult and time consuming, but on the other hand it is one time job and by spending few more hours in planning can save from lot of work in the future.

Tags: