63

Migrating Work Items Between Azure DevOps Organizations

Moving your project from one Azure DevOps (ADO) organization to another can be challenging, especially when you want to maintain the status of your work items. This two-step migration process offers a practical solution that preserves your workflow states without requiring complex tools.

Azure DevOps Work Item Migration between Organizations

The Challenge of Work Item Migration

When migrating between Azure DevOps organizations, work items don’t automatically transfer. The standard import/export process typically resets all statuses to the default state (usually “New”), disrupting your project’s workflow visibility and reporting.

This method solves that problem through a strategic two-phase import approach.

Prerequisites

Before starting, ensure you have:

  • Admin access to both Azure DevOps organizations
  • Identical process templates in both organizations (Agile, Scrum, etc.)
  • Matching workflow states between organizations
  • Excel or similar spreadsheet software

Step 1: Initial Export and Preparation

First, we’ll export the work items and prepare them for the initial import:

  1. Export work items from your source organization

  2. Prepare the CSV file for first import

    • Open the exported CSV in Excel
    • Remove the ID column (each ADO instance generates unique IDs)
    • Create a backup copy of this file (we’ll need it later)
    • In the copy, remove the Status/State column
    • Save this modified copy for import

Step 2: First Import and Status Restoration

Now we’ll perform the initial import and then restore the original statuses:

  1. Import the modified CSV to the target organization

  2. Export the newly imported work items

    • Create a query in the new organization to view all imported items
    • Export these items to CSV

  3. Restore original statuses

    • Open both the newly exported CSV and your original backup
    • Copy the Status/State column from the original file
    • Paste it into the corresponding position in the new export
    • Save this combined file

  4. Final import with correct statuses

    • Import this combined CSV back into the new organization
    • This will update the existing work items with their original statuses

Common Issues and Solutions

Mismatched Process Templates

If your organizations use different process templates, you may need to map status values. Create a translation table to convert statuses from one template to another before the final import.

For more information on process templates, visit: https://learn.microsoft.com/en-us/azure/devops/boards/work-items/guidance/choose-process

Handling Relationships

This method doesn’t preserve parent-child relationships or links between work items. After migration, you’ll need to manually reestablish these connections.

Learn more about work item relationships: https://learn.microsoft.com/en-us/azure/devops/boards/queries/link-work-items-support-traceability

Attachments and History

Work item attachments and history won’t transfer with this method. Consider using the Azure DevOps Migration Tools for a more comprehensive migration if these elements are critical.

For advanced migration options: https://github.com/nkdAgility/azure-devops-migration-tools

Conclusion

  • This two-step migration approach offers a straightforward way to move your work items between Azure DevOps organizations while maintaining their workflow states. While it doesn’t preserve every aspect of your work items, it keeps the most critical information intact without requiring specialized tools.

    For official Microsoft documentation on importing and exporting work items: https://learn.microsoft.com/en-us/azure/devops/boards/queries/import-work-items-from-csv

    Have you tried migrating between ADO organizations before? What challenges did you face? Share your experiences in the comments below!