Migrating from Jira to Azure DevOps

As far as I’m concerned, a team can use any tool they want to track their work items and planning. But, my personal favourite is Azure DevOps. Currently I’m helping some teams moving their Jira projects to DevOps and this blog explains how you can do this, too!

Uniformity and standards

For several reasons it can be frustrating if teams use multiple tools for the same purpose. For sake of uniformity, I believe it is best to have standards within your company. In the case of my current customer, that standard is Azure DevOps.

Obviously you want to migrate your work from the old to the new platform. Azure DevOps has the ability to use APIs to ingest data, and you can export Jira as well. To do this manually and figure out all the moving parts, you will have quite a challenge.

Enter Solidify

I was pointed to a really great tool by the team of Solidify, the Jira to Azure DevOps work item migration tool.

The Jira to Azure DevOps work item migration tool lets you export data from Jira and import it as work items in Azure DevOps or Microsoft Team Foundation Server

This sounds exactly like what we need! Because every project is different, it can be tricky setting up all the mapping of statuses, and figuring out how to connect to the correct instances.

The documentation of the tool is great, but this blog will give a step-by-step approach on how to do a migration.

Getting the tool

The Github link in the beginning of this post is the starting point for all documentation of the tool. To download the release directly, point your browser to solidify/jira-azuredevops-migrator/releases.

Preparing for your Jira export

The Github repo contains samples at this location. Worth noting is that the setup of the configuration file is essential. See the first few lines of the file below:

"source-project": "MyJiraProject",
"target-project": "DevOps Project Name",
"query": "project = 'MyJiraProject'",
"workspace": "C:\\Temp\\JiraExport\\",
"epic-link-field": "Epic Link",
"sprint-field": "Sprint",
"download-options": 7,
"batch-size": 20,
"log-level": "Info",
"attachment-folder": "Attachments",
"user-mapping-file": "",
"base-area-path": "",
"base-iteration-path": "",
"ignore-failed-links": true,
"process-template": "Agile",

As you can see, the source and target fields correspond with your data in Jira and DevOps respectively. The process-template field corresponds to what you have setup in DevOps, like CMMI, Scrum or Agile (or Basic).

Next to setup, are the mappings. As you might know, some tasks, statuses or other properties differ in Jira and DevOps. Let’s say you have a Task in Jira with status Review. You might not have the same status in DevOps, so you want to map that to another status type. The same goes for types like ‘User Story’ or ‘Epic’:

"type": [
{
   "source": "Feature",
   "target": "Feature"
},
{
   "source": "Epic",
   "target": "Epic"
},
{
   "source": "Story",
   "target": "User Story"
},
{
    "source": "Bug",
    "target": "Bug"
},
{
    "source": "Task",
    "target": "User Story"
},
{
    "source": "Sub-task",
    "target": "Task"
}
]

Within the configuration file, you should specify all these mappings. If you fail to add one, the export tool will generate an error, so you can add the missing mapping and re-export Jira.

Running the Jira Export tool

If the config file is setup, you can run the tool using the following command:

jira-export.exe -u p.rombouts@yourdomain.com -p api-token-here --url https://yourinstance.atlassian.net --config config.json

As you can see I’ve setup the command using the API token. Please refer to this page on how to get an API token for Jira. In theory a password should work, but it did not work in my case.

Inspecting the export results

When the tool runs, you will see results directly in your CLI interface:

$ jira-export.exe -u username -p apitoken --url https://something.atlassian.net --config config.json
Jira Exporter v2.2.25
Copyright (c) Solidify
Wow, there's a newer release out (v2.2.31)! We recommend downloading it for latest features and fixes.
[I][10:12:11] Connecting to Jira...
[I][10:12:11] Retrieving Jira fields...
[I][10:12:12] Retrieving Jira link types...
[I][10:12:12] Export started. Exporting 705 items.
[I][10:12:13] Initializing Jira field mapping...
[I][10:12:14] Processing 1/705 - 'Item-790'.
[W][10:12:14] Could not find user 'someuser1@yourdomain.com' identity in user map. Using original identity 'someuser1@yourdomain.com'.
[W][10:12:15] Could not find user 'someuser2@yourdomain.com' identity in user map. Using original identity 'someuser2@yourdomain.com'.
[I][10:12:15] Processing 2/705 - 'Item-789'.

As seen in the above start of the export, some users could not be found in the mapping. This is done on purpose by me; I want the exact same users from Jira to be used in Azure DevOps. Optionally you could create a users.txt file, and map users in Jira to different users in Azure DevOps. If any fields or mappings are missing, you will also see this in your console.

Bonus: In the export directory specified in the config tool, the output is also saved to a file called something like jira-export-log-190809-101211.txt. So you do not need to save the output yourself and just let it roll!. The export can take quite some time, so sit back and grab a coffee.

Running the Azure DevOps Import tool

If the previous step completed without any mishaps, and all looks OK in the log file, you can import your Jira exported data into Azure DevOps.

Again using the same config file, you can run the following command:

wi-import --token personal-access-token-here --url https://yourorganisation.visualstudio.com --config config.json --force

As you can see I’ve setup the command using the Personal Access Token. Please refer to this page on how to get one for Azure DevOps.

Again this tool will provide you with verbose information, and will also dump a logfile to the same folder as where the Jira export resided.

If everything went OK; you are now good to go in Azure DevOps!

Finalizing and cleaning up

Process wise it is smart to plan this ahead, with your team. You should have a cut-over date, and make sure that access to the old Jira project is read-only, or turned off, after you’re done exporting/importing. You do not want to maintain two boards for a team!

Conclusion

Hope you find this manual useful, the tool helped me out a great deal. The documentation is excellent and it is actively maintained by the fabulous team of Solidify. Can’t thank you guys enough!