Migrate Work Items from JIRA to Azure Boards

Aammir Mirza
4 min readSep 3, 2023

This tool lets you migrate work item from Jira to Azure DevOps or Microsoft Team Foundation Server. The tool has two parts, first Jira issues are exported to files then we import the files to Azure DevOps/TFS. We believe this is a good approach to migration since it allows you to export the data to migrate and validate it before importing it. It also makes it easy to migrate in batches.

Some of the capabilities include:

  • Export Jira issues from Jira queries
  • Map users from Jira to users in Azure DevOps/TFS
  • Migrate work item field data
  • Migrate links and attachments
  • Migrate history

How to get the tool ?

Use the link to clone the migration tool Link


Step 1- Setting up the configuration and mapping

We will be migrating JIRA project to Azure DevOps Boards. Since we want to migrate our Jira demo project to a Scrum template in Azure DevOps, we’re going to use the sample configuration file that is based on the Scrum template in Azure DevOps. The sample configuration file is placed in the folder Samples and it’s called config-scrum.json. The complete documentation of every field is available here.

In the query we´re using to all WI’s within the project IICS project = IICS, if you only want to export User stories and Sub tasks, then it will filtered as project = IICS AND issue type in (Story, Sub-task) ORDER BY Rank ASC. The workspace where the Jira items will be exported in the form of json files are going to end up in C:\Temp\JiraExport\IICS and the Area Path and Iteration path in Azure DevOps are both set to "IICS”, so we can easily distinguish the migrated items and move them elsewhere.

The configuration has also mapped standard Jira items to their respective Azure DevOps work item types based on the Scrum template from Microsoft, so it will look like this:

  • Feature = Feature
  • Epic = Epic
  • Story = Product Backlog Item
  • Bug = Bug
  • Task = Task
  • Sub-task = Task

The standard Jira fields are mapped to the standard Azure DevOps fields as well.

For any work item we export that is of type Task we’re mapping states like this:

  • To Do = To Do
  • Done = Done
  • In Progress = In Progress

In the same way for type Bug, Product Backlog Item, Epic or Feature we’re mapping states based on Azure DevOps available states.

The Scrum template is the one that differs depending on work item type. Agile and CMMI templates are more straightforward when it comes to states for work item types.

Step 2 : Export from JIRA

  1. Open a cli of your choice and navigate to where the extracted zip file exists. In my case I’ll open a Command Prompt and write: cd C:\Temp\jira-azuredevops-migrator-2.0.2
  2. Make sure your updated config-scrum.json and users.txt are in the root
  3. Collect the access keys you need for Jira:
  • Identify the migration account (username and password) to access Jira
  • Get the URL to Jira and the name of the source project
  1. Run the export tool by typing the following command:

jira-export -u jiraaccount@some.domain -p JIRA_APIKey--url https://my.jira.url --config sample\config-scrum.json --force

Output for exporting JIRA WI’s
This is how the exported stories looks like.

So finally we have completed the haf process of migration, now we need all the WI’s to be moved to Azure DevOps.

Step 3 : Import to Azure DevOps

Now we’re ready to import the items to Azure DevOps.

  1. Collect the access keys you need for Azure DevOps:
  • Get the URL and name of the target Azure DevOps organization
  • Acquire a personal access token for the organization here with at least work item read/write permissions
  • Get the name of the target project (the import tool will create the target project if it does not already exist)

2. Run the import tool by typing the following command:

wi-import --token AzureDevOps_PAT--url https://my.azuredevops.url --config sample\config-scrum.json --force

Mission Accomplished
Verified the work items creation in Azure DevOps



Aammir Mirza

Cloud Architect with 12 years of experience in managing cloud infrastructure and automation, integrating Azure cloud-based infra components