Migration-project-between-Azure-DevOps-Cloud

This repository demonstrates a successful project migration from one Azure DevOps organization to another. The migration process involved the transfer of Work Items, Test Plans & Suits, Teams, and Shared Queries. The migration strategy was carefully planned to ensure the integrity of the data and the preservation of dependencies. Test Cases were migrated first, followed by Test Plans. Test Suites were then manually created in the destination organization. This approach ensured the successful migration of all project components while maintaining the necessary relationships and configurations.

Services/Tools used in the project:

• PowerShell

• Azure DevOps Services

• Azure DevOps Migration Tools developed by (Martin Hinshelwood)

Steps:

• Introduction

• Getting Environment Ready

• Preparing The Destination Project

• Preparing JSON File

• Migrate Test Cases

• Migrating Shared Queries

• Migrating Work Items

• Dry run

Introduction

Using the Azure DevOps Migration Tools to migrate a project from the source organization to the destination organization, which includes Work Items, Test Plans & Suits, Teams, and Shared Queries.

Getting Environment Ready

Before starting the migration, make sure to have

1. Download & Install Azure DevOps Migration Tools

1.1 Install

In order to run the migration you will need to install the tools first.

1. Install Chocolatey from https://chocolatey.org/install

2. Run [winget install nkdAgility.AzureDevOpsMigrationTools] to install the tools [source] https://devopsmigration.io/download/

The tools are now installed here in this location %Localappdata%\Microsoft\WinGet\Packages\ and then Creates symbolic link for devopsmigration command`.

Run from anywhere using devopsmigration init

Now the configuration.json in Temp location

Preparing The Destination Project

1. Migration State:

In order to store the state for the migration you need to use a custom field, the ReflectedWorkItemId field, which needs to be added to the Target only.

1. Open your Azure organization setting
2. Open Process Settings

3. Open Your Inherited Process Settings

4. For Each Work Item Type, Open it and repeat the following steps

5. Click New Field

6. In the Create Field Dialog, Set the New Field name to ReflectedWorkItemId

7. Make sure it’s of Type Text Single Line

8. Click Add Field

Make sure you have added the field to all Work Item Types, You can check the Work Items (to make sure you have added the field) by Going to Your Inherited Process and checking every work Item.

Reference: https://docs.microsoft.com/en-us/azure/devops/organizations/settings/work/add-custom-field?view=azure-devops

2.Process Customization:

In this step, I customized the Inherited Agile process template as required :

1. Building a field customization layout:

1.1. Open your Azure organization setting

1.2. Open Process Settings

1.3. Open Your Inherited Process Settings

1.4 For Each Work Item Type, Open it and repeat the following steps

1.5 Click on the dots at the inherited group

1.6 Click New Field

1.7 In the Create Field Dialog, Set the New Field name to Business Team

1.8 Make sure it’s of Type Text Single Line

1.9 Click Add Field

You can check the Work Items (to make sure you have customized the layout) by Going to Your Inherited Process and checking every work Item layout.

Note: Repeat the field customization layout process for each work item in the inherited process template in the destination project as required..

2. Build & Customize the States:

2.1 Open your Azure organization setting

2.2 Open Process Settings

2.3 Open Your Inherited Process Settings

2.4 For Each Work Item Type, Open it and repeat the following steps

2.5 Click on States

2.6 Click on New state

2.7 In the Name Dialog, Set the New State name to Development

2.8 In the Name State category, Set the New State name to In Progress

2.9 In the Color category, Set the desired Color

2.10 Click Create

I can check the Work Items (to make sure you have customized the States) by Going to Your Inherited Process and checking every work Item States.

Note: Repeat the State customization layout process for each work item in the inherited process template in the destination project as required.

Preparing JSON File

Navigate to C:\tools\MigrationTools then Open configuration.json from the current directory

1. In Endpoints, I set the values for the Source Project:

Organization: Organization URL

Project: Source Project Name

AuthenticationMode: Access type name

AccessToken: XXXXXXX

2. In Endpoints, I set the values for the Target Project

Organization: Organization URL

Project: Target Project Name

AuthenticationMode: Access type name

AccessToken: XXXXXXX

3. In ChangeSetMappingFile, I set the values for the Source Project

Collection: Organization URL

Project: Source Project Name

AuthenticationMode: Access type name

AccessToken: XXXXXXX

4. In ChangeSetMappingFile, I set the values for the Target Project

Collection: Organization URL

Project: Target Project Name

AuthenticationMode: Access type name

AccessToken: XXXXXXX

5. In FieldMaps, I used the FieldMergeMapConfig method for each work item to store the Archived data from the source project into a specific layout page into the source project

"$type": "FieldMergeMapConfig" (In case of migration of multiple fields, use this mapping method)

WorkItemTypeName: Work item name

sourceFields: Field Reference Name I got the Field Reference Name from the inherited process of the source project.

targetField: Field Reference Name In this dialogue, I have created a New page with a New field with the name: Data Archived from Old project to store the archived data from the source project.

formatExpression: I have listed the names of the unused fields which will be reflected in the Data Archived layout page of the target project.

6. In FieldMaps, I used the FieldValueMapConfig method for each work item to configure & value mapping the states for each work item*

7. Processors are the control units for migration, each processor controls the migration of a specific part of Azure DevOps Project. Remember: If you want a processor to run, its Enabled attribute must be set to true

8. Each processor has an Enabled attribute, which is either true or false, if it’s enabled (true) then this processor will be executed during migration.

9. 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

Migrate Test Cases

Note: Migrating Test Cases First When planning our data migration, we prioritize Test Cases for a good reason:

• Dependency: Test Cases are often linked to Test Plans through Test Suites.
• By migrating Test Cases first, we ensure that when we later migrate the Test Plans, the associated Test Cases already exist in the destination organization.

1. I started the migration with Test Cases along with their attachments to the Target Project, This is its configuration at the Processors in the JSON file: "WIQLQuery": "SELECT [System.Id] FROM WorkItems WHERE [System.TeamProject] = @TeamProject AND [System.WorkItemType] = 'Test Case"`

2. Now To Migrate Test Cases, Let’s get back to the JSON File:

• Enable the TfsWorkItemMigrationConfig processor by setting Enabled to true
• Set "WIQLQuery": "SELECT [System.Id] FROM WorkItems WHERE [System.TeamProject] = @TeamProject AND [System.WorkItemType] = 'Test Case"`

3. From any location run devopsmigration execute -c "D:\projects\configuration.json" file pass is depends on your location

4. Once finished you’ll see something like this:

Here is how the Target Project Looks like after Migration

Migrating Shared Queries

1. Now Let’s move to the Migrating of Shared Queries, Here are the Shared Queries before migration:

2. Now To Migrate Shared Queries, Let’s get back to the JSON File:

• Set the processor "$type": "TfsWorkItemMigrationConfig", Enabled to false
• Set the processor "$type": "TfsTestVariablesMigrationConfig", Enabled to false
• Set the processor "$type": "TfsTestPlansAndSuitesMigrationConfig", Enabled to false
• Enable the processor "$type": "TfsSharedQueryProcessorOptions", by setting Enabled to true

3.From any location run devopsmigration execute -c "D:\projects\shared_queries.json" file pass is depends on your location

4. Once finished you’ll see something like this:

Here is how the Target Project Looks like after Migration

Migrating Work Items

1 Now To Migrate Work Items, Let’s get back to the JSON File:

• Enable the processor "$type": "TfsWorkItemMigrationConfig", by setting Enabled to true
• Set the processor "$type": "TfsTestVariablesMigrationConfig", Enabled to false
• Set the processor "$type": "TfsTestPlansAndSuitesMigrationConfig", Enabled to false
• Set the processor "$type": "TfsTfsSharedQueryProcessorOptions", Enabled to false

2 From any location run devopsmigration execute -c "D:\projects\all_work_items.json" file pass is depends on your location

3 Once finished you’ll see something like this:

4 And Finally, here is the Work Items

Dry run

*Prior to the actual migration, a pre-dry run will be performed. This involves testing a sample configuration to ensure that field mappings for custom fields align with the process template. If any conflicts or differences are identified, they will be correct to match the source field references in the main configuration file.

Full Dry run:

• Along with all that mentioned steps a full dry run will be conducted to ensure that all configurations are functioning correctly
• The first dry run can be performed without any downtime for the source project, allowing for an estimation of the actual migration process.
• Once the dry run is completed successfully, the actual migration can commence. It is advisable to schedule the migration on weekends to minimize downtime during the process..