Appfire Position Statement on the Ukraine War and Russia. Read here

Spartez Software has joined the Appfire family. Learn more

The Comprehensive Guide for Jira Azure DevOps Integration

Agnieszka Józwiak
Agnieszka Józwiak
Mar 17th, 2020

Switching from Azure DevOps to Jira Software is a real-life scenario and a challenge as well. There are several business reasons to back up that meaningful decision. The exponential growth of your company and merging it with another enterprise are on the top of the list. But how to conduct a process and don’t get lost in it? How not to jeopardize your sensible project data? Here’s our complete guide to handling your Jira Azure DevOps Integration.

In our last article, we pulled back the curtain to see the differences between uploading your Azure DevOps data to Jira by using a CSV file and getting your hands on the TFS4JIRA application.

The key takeaway was that there’s no point in doing it manually (following a CSV path) and putting all your previous project work at such a risk. Going for the TFSJIRA plugin was an undeniable winner in this clash.

In this article, we will focus on creating a step-by-step guide on how to make this transition come true.

The Jira Azure DevOps integration action plan

Here’s what steps you need to take when it comes to integrating those two top ALM solutions, and migrating your data from one system to another:


  • Getting to know TFS4JIRA system requirements.
  • What TFS4JIRA components do you need to install?
  • Installing the TFS4JIRA plugin in Jira.
  • Installing the TFS4JIRA Synchronizer.
  • Setting up a license.
  • Running a network configuration.


  • Permissions needed by TFS4JIRA Synchronizer
  • Configuring TFS / Azure DevOps check-ins synchronization
  • Configuring issues and work item synchronization
  • Configuring user credentials for Azure DevOps Services (formerly VSTS)
  • Settings for Jira Cloud
  • Setting TFS4JIRA Synchronizer application access permissions
  • Configuring TFS check-ins scanner in JIRA plugin (deprecated)
  • Mail Notifications


  • TFS / Azure DevOps (formerly VSTS) check-ins synchronization
  • TFS / Azure DevOps (formerly VSTS) to-and-from JIRA issues synchronization

Looks like a complicated process? It might, but the business result is unmatched. Besides, by choosing this path, you save your company from unnecessary expenses (if you decide to outsource the entire transition) or time-wasting (if you stick to the idea of copying and pasting your data manually).

Let’s break it down:

The installation phase

Since you decided to move from one ALM solution to another with a tool that has a successful history of thousands of downloads, it’s time to do it right:

Getting to know TFS4JIRA system requirements

Like in every piece of software, the installation of our app means facing some system requirements, such as an operating system or a list of supported browsers.

To get a quick overview, take a look at this TFS4JIRA compatibility matrix:

What TFS4JIRA components do you need to install?

To kick it off, you need to install the Jira Azure DevOps / TFS migration and integration app – the TFS4JIRA.

The Atlassian staff picked application consists of two elements, and it’s crucial to install both of them - TFS4JIRA Jira plugin and TFS4JIRA Synchronizer.

Installing the TFSJIRA plugin

TFS4JIRA Jira plugin will work for both – Jira Server and Jira Cloud. When it comes to Jira Server, there are two ways to take it from here:

  • You either go to the Atlassian Marketplace page dedicated to TFS4JIRA, take a glimpse at some encouraging reviews from happy users, and install it.
  • Or – you can choose the Manage Add-ons Jira Screen option, which we recommend. Check the detailed instruction here.

Installing the TFS4JIRA Synchronizer

When you’re done, your second move will be about installing the TFS4JIRA Synchronizer backend web application. This app complements the plugin and makes the synchronization possible. Regardless of whether you use a cloud or on-premise version of TFS and Jira, this Synchronizer is your weapon of choice. Check the installation process here.

Setting up the license

It’s a standard procedure that apps available on Atlassian Marketplace come together with a license.

By purchasing the license, you will empower your company with an app that is not time-limited.

What’s more, it’s a year guarantee to get any updates of the application and most importantly, something that we’re genuinely proud of – the support that will give you a helping hand with all the integration and migration bits and pieces!

Here’s a random opinion that proves the proficiency of our support team:

“The support team is great. I had one-to-one support, and they aided me through all the issues that I had. Our TFS4JIRA is now set up and running great. Keep up the good work, guys!”

Get more details about buying the TFS4JIRA license here.

Running a network configuration

There are several types of instances that need to communicate with each other to make the synchronization possible. You might have been working on TFS / Azure DevOps Server or on Azure DevOps Services. And now you might be willing to make a switch to Jira Server or to Jira Cloud.

How to connect the dots and start moving your tasks and projects from one environment to another?

You need to pay attention to the rules of your network architecture. Take a closer look at those handy visuals:

Jira Server + TFS / Azure DevOps Server

Jira Server + TFS / Azure DevOps Server

Jira Server + Azure DevOps Services

Jira Server + Azure DevOps Services img

Jira Cloud + TFS / Azure DevOps Server

Jira Cloud + TFS / Azure DevOps Server img

Jira Cloud + Azure DevOps Services

Jira Cloud + Azure DevOps Services img

Go here to get more technical details.

The configuration phase

OK! So, the system requirements, installing the plugin and the Synchronizer, buying the license, and rearranging your network infrastructure, are behind you, it’s time to enter the second phase – the configuration.

Permissions needed by TFS4JIRA Synchronizer

To transfer all your previous and current work from Azure DevOps to Jira, you need to synchronize work items with issues. TFS4JIRA Synchronizer is the tool that’s going to make that happen, but it needs some credentials to connect with both platforms.

How to synchronize Jira issues with TFS / Azure DevOps work items?

The Synchronizer needs a set of permissions from Jira and TFS / Azure DevOps as well.

Here are the permissions from Jira:




Add Comments


Only if Comments synchronization is enabled

Assign Issues


Only if the Assignee field is mapped

Browse Projects

Close Issues

Create Attachments


Only if Attachment synchronization is enabled

Create Issues

Delete Issues


Only if you want TFS4JIRA to delete issues that were not sync'ed properly

Edit All Worklogs


Only if Time Tracking fields are mapped

Edit Issues

Link Issues


Only if links are mapped (e.g. Epic Links)

Modify Reporter


Only if the Reporter field is mapped

Resolve Issues

And permissions you will need from TFS / Azure DevOps:

User Group




Minimum set of permission




Bypass rules on work item updates


TFS / Azure DevOps check-ins synchronization

Now, whereas the above credentials were provided in the synchronization profile, TFS4JIRA Synchronizer also has to connect to Jira with the credentials in the check-ins scanning configuration.

Here are the permissions you need to face when it comes to Jira:




Browse Projects

Edit Issues


Required in TFS4JIRA > 7.4 No longer required in TFS4JIRA 7.5 or newer

View Development Tools

And for TFS / Azure DevOps





Permission to read the repository

View project-level information

User needs to be able to view the project

How to configure TFS / Azure DevOps check-ins synchronization

As soon as you started to use Jira and created a set of issues and projects, you can use the TFS4JIRA app to view TFS / Azure DevOps check-ins that are connected to those issues.

To put that to action, take a deep dive into detailed instructions listed below:

  1. Overview of components needed to synchronize TFS check-ins,
  2. Configuring TFS4JIRA Check-ins synchronization:
    1. Configuring TFS4JIRA check-ins synchronization using existing TFS4JIRA synchronization profile,
    2. Configuring TFS4JIRA check-ins synchronization from scratch,
  3. Connecting JIRA to TFS4JIRA Synchronizer.

How to configure issues and work items synchronization

When your company is in the transition phase, you can’t allow yourself to slow down your projects and keep your customers waiting for delivered products. Some of your work might still be in Azure DevOps, while new tasks already live in the new Jira reality.

Obviously, you can’t afford delays, and you also wouldn’t want to gamble on losing data by copying and pasting from one platform to another.

Therefore, getting Jira issues in sync with Azure DevOps work items is the essence of this significant realignment.

  • It is possible thanks to the TFS4JIRA Synchronizer:

Create a synchronization profile

Let us walk you through the process. First, go to your TFS4JIRA Synchronization and hit the Create Synchronization Profile button in the Synchronization Configuration tab.

Create a synchronization profile img

Next, after a glimpse at a welcome screen, you need to follow these steps:

  • Create your profile name – simple as that:

azure devops jira img 2

  • Enter your Jira credentials, like URL, username, and password. Validate them by clicking the “Test connection” button:

azure devops jira - enter credential img

  • Then, type in your TFS / Visual Studio Team Services settings. The Synchronizer needs to connect with your original work environment in TFS:

TFS / Visual Studio Team Services settings img

  • Now, you are ready to set up your synchronization. This is pure gold! You can easily define that all the changes made in Jira will reflect parallel updates in TFS / Azure DevOps, the other way around, or both directions. What’s more, you can independently synchronize comments, attachments, and particular projects!

set up your synchronization jira and azure img

  • Create custom fields for Jira and TFS. It will enable Synchronizer to store information about paired issues and work items. More on this here.

Create custom fields for Jira and TFS img

  • Type Mapping is your next step. It will allow you to map specific types of Jira issues with their TFS / Azure DevOps counterparts. Take a look:

Type Mapping img

  • Although State Mapping looks pretty much like Type Mapping, it relates to a different parameter. In this step, you map issues and work items concerning their statuses. It can be tricky, so try to select values on both sides to be as similar as possible.

azure devops jira integration img 3

  • Mapping links is a crucial aspect in terms of project management. It’s a tool that helps you to take all the relations between work items and their hierarchy with you. Click here for more.

Mapping links img

  • Subtasks Mapping – the name of this step speaks for itself. It’s all about mapping subtasks created in both instances.

Subtasks Mapping img

How does it look like in real life? Let’s say you created a task in Jira, and then a subtask related to it. The subtask mapping will result in creating a parent/child link in TFS / VSTS:

parent/child link in TFS / VSTS img

  • Each issue in Jira has its fields that come in handy in working on particular tasks – who is the assignee, and who is the reporter; what is the label for an issue or when is it due. With Field Mapping tool you can connect all those fields to their equivalents in TFS.

fields tfs jira

For more in-depth intel on how to synchronize user fields click here.

  • Value mapping. If anything changes in the mapped fields, the Synchronizer needs to know how to apply those values on the other side of the barricade.

azure jira synchronizer

View, manage, and edit your profiles

As soon as you went through the synchronization and mapping bits and pieces, you can check the information of your synchronization profiles (such as name, status, the date of the last run) and make some changes - enable / disable, check-ins scanning, initial synchronization, edit (you can find a detailed description here), clone, delete.

synchronization profiles

Synchronize filters, Area path and Iteration Path Fields

When you create your synchronization profile, it has no filters by definition, and it means that the app will synchronize ALL the issues and work items. You can, however, make use of synchronizing filters option to narrow down the number of synchronized elements coming from both sides.

There are no limits here – you can add as many filters as you like, but try not to push it because you will find yourself close to the default situation where everything is matched. More on this here.

sync filters

But there’s more. With TFS4JIRA Synchronizer, you can take your agile work heritage with you. All those sprints your team was working on can be entirely transferred to Jira. How? By synchronizing Three Paths (also known as area path or iteration path fields) from TFS with Jira.

jira azure migration img

Mapping states, statuses, and links

As we mentioned before, mapping and synchronization works in both directions. You can take the advantage of that fact if you have too many states /statuses in TFS / Azure DevOps, and you would like to translate it to a single one in Jira.

Example? If you have many states in Azure DevOps marked as both – Done and Closed (which means the same), you can map it with a single Done status in Jira.

Mapping links also come in handy for transferring entire projects from one to another. Issues, as well as work items, can have a history of related work framed into link relations such as parent/child, relates to/related to, etc. The good news is, you can synchronize them as well.

fields mapping 1

fields mapping 2

Synchronize the hierarchy

The relationship between the tasks is crucial for a better understanding of the scope of work, but it’s also essential to know its hierarchy. In terms of TFS / Azure DevOps, we’re talking about: Epics/Features, User Stories, Tasks/Bugs. Whereas in Jira, we’ll be looking at Epics, Stories/Tasks, Sub-Tasks.

Now, you wouldn’t want to leave all that behind you. How to take care of it and migrate the hierarchy? Watch this video to find out!

Configure user credentials for Azure DevOps

Another step in the TFS4JIRA configuration stage will be about configuring user credentials for TFS / Azure DevOps.

We will show you a recommended way of authenticating your Azure DevOps in terms of TFS4JIRA, and it will involve creating a Personal Access Token. To do that, you need to go to your account in Azure DevOps and click your avatar to expand the drop-down list:

configuring user credentials for TFS / Azure DevOps 1

After clicking the Security link, and choosing the Personal access tokens, you should create your New Token:

configuring user credentials for TFS / Azure DevOps 2

Next, give this token a name and an expiration date:

Last, copy the generated token and paste it in TFS4JIRA Synchronizer profiles configuration:

configuring user credentials for TFS / Azure DevOps 3

Other TFS4JIRA configuration aspects

  • Settings for Jira Cloud. As we highlighted at the beginning of this article, TFS4JIRA works for Jira Server and Jira Cloud. If you’re into the second option, you will have to install the Synchronizer in your local network. Click here to find out more.
  • Setting your TFS4JIRA Synchronizer application access permissions. To take care of the access control, you will have to face a standard windows authorization rules. After entering credentials, you need to grant access to the application.
  • Mail notifications. There are a few elements to set as far as emails you will receive from the applications.

Over to you

OK, that was quite a journey! Thank you for keeping the pace – the above stages and steps may strike you as scary, but the business stake of the entire transition process from TFS / Azure DevOps to Jira is unmatched!

Going through the procedure delivered by the TFS4JIRA application, you will anyway save tons of unnecessary and inefficient work, long hours of mundane clicking, or irrational expenses (if you wanted to outsource the migration to another company).

So, time for you to make a meaningful move – try the TFS4JIRA on a free trial!