Migrating Inherited Process in Azure DevOps

Posted Oct 21, 2023 Updated Jun 25, 2024

By Rehab Ragab

3 min read

In this post, we’ll explore how to migrate a customized inherited process from one Azure DevOps organization to another. We’ll walk through the process using the powerful process-migrator tool, developed by Microsoft.

Prerequisites

Before we dive into the process migration journey with the process-migrator tool, let’s make sure your environment is ready. To get started, you’ll need to have Node.js and NPM installed on your machine.

1- Verify Node.js Installation

Open your command prompt (cmd).
Type node –version and check if Node.js is installed. If it’s not installed, we’ll need to proceed with the installation.

2- Download Node.js

Visit node.js.org to download the latest LTS version, which includes npm.

3- Select Your Installer

Choose the installer that matches your machine. For example, if you’re using Windows, select the Windows Installer.

4- Installation

Locate the downloaded Node.js installer and double-click it to begin the installation, as shown in the screenshot below.

5- Verification

To confirm the successful installation of Node.js, repeat Step (1) by opening your command prompt and running node --version. This time, you should see the installed Node.js version displayed.

Installing process-migrator

Now that your environment is ready, install the process-migrator tool by running the following command in your command prompt (cmd):

npm install process-migrator -g

Creating the configuration file

Navigate to the desired location where you want to create the configuration file.
Run the command process-migrator. This will generate the configuration file in the specified location.

This is how the created configuration file looks like:

Preparing the configuration

To configure the process-migrator tool, you’ll need to specify the following parameters in the configuration file:

sourceAccountUrl: This is the URL of your source organization in Azure DevOps.
sourceAccountToken: Your Personal Access Token (PAT) for the source organization.
targetAccountUrl: This is the URL of your target organization in Azure DevOps.
targetAccountToken: Your Personal Access Token (PAT) for the target organization.
sourceProcessName: The name of the source process to be migrated.

1- Copy the URL of your Source Organization and paste it for sourceAccountUrl.

2- Copy the URL of your Target Organization and paste it for targetAccountUrl.

3- Create PAT for both the source and target organizations.

Here’s how to set up your PAT:

For the Source Organization:

1- Click on your user settings and select “Personal Access Token”.

2- Click New Token.

3- Enter the following details:

Name
Ensure you’ve selected the Source organization.
For PAT scope, choose custom-defined, and ensure the “Work Items” permission has Read, Write, & Manage checked.
Click Create

3- Copy the value of the PAT, and paste it for sourceAccountToken

Repeat these steps for the Target Organization to create a PAT and paste its value for targetAccountToken.

4- Go to the Source organization to copy the source process name, and then paste it for sourceProcessName.

After defining all the required parameters, your configuration file should look something like this:

NOTE: The configuration file is in JSONC format, which means you don’t have to remove comment lines for it to work.

Running the Migration

You’re all set to start the migration process. Simply open the command prompt (cmd) and type:

process-migrator

NOTES:

You can also specify the following switches:
- --mode=<migrate (default)/import/export>: Choose the migration mode.
- --config=<your-configuration-file-path>: Specify the path to your configuration file.
When running the command from the configuration file location, it is optional to specify the configuration file path. If the configuration file is located elsewhere, you should add its path using the --config switch. The full command would then be: process-migrator --config=<your-configuration-file-path>.
The tool’s default mode is migrate, so it is optional to specify it. However, if you intend to use the tool for import or export only, you should specify the mode using the --mode switch. The complete command would be: process-migrator --mode=import/export.

Migration Process:

The tool will start by exporting the Source process template to a JSON file.
Subsequently, it will import the exported template into the Target organization.

Verification:

Once the migration is successfully completed, you can review all work item types.
Verify that their fields, states, and rules have been migrated successfully.

Here are the Target organization processes before and after the Migration:

Before Migration: