Jira to VSTS Migration: migrating work items

House icon

Published November 29, 2017

So, you decided to move from Jira to VSTS but don’t want to leave your data behind. You have months or years of valuable project tracking information in Jira and you want to continue working in an organized and traceable way without disturbing the work of project managers and developers. To achieve that, both current and old issues should be available from the new planning tools. In addition, you want to keep the important historical context.

Jira and VSTS planning tools are similar in quite a few ways, as they are both aimed at solving the same set of problems. However, as one would expect, they do have different takes on these problems. Examples include slightly different terminology and different implementation, to name a few. This results in migration of existing data not as simple as one might wish.

In this blog post, we’ll look at how to approach a Jira to VSTS (Visual Studio Team Services) migration. We will also consider the expectations and possibilities for what data we would like to preserve as well as some key adjustments to make in that transition.

What do we need to migrate?

Let’s take a look at what we want to migrate when transitioning from Jira to VSTS:

  • Issue properties
  • Links between issues
  • Attachments
  • External artifact connections (builds, commits)
  • Structural (backlog/sprint) information: when do sprints start/end? Which sprints have which items assigned them? Backlog priority?
  • Historical information: who created which issue, and when? Who closed it and when? When was it reopened? Was a link added at the same time?

Workflow and naming adjustments

Both tools support heavy customization, from minor modification on out-of-the-box process templates to defining one-of-a kind processes. Regardless of whether you just use plain Jira or if you’ve modified the workflow heavily, the first step is to consider your current practices and how they correspond to what you’ll be trying to achieve in VSTS. As an example, let’s look at some of the differences between Scrum process templates in Jira and VSTS.

When transforming a Jira issue into a VSTS work item, the first thing you’ll have to do is decide which type will the resulting work item be.

Type and hierarchy differences

Let’s compare the two different types:

Fig 1. Jira Issue Type Hierarchy

Fig 2. VSTS Work Item Type Hierarchy

In the pictures above we see that the difference is not just in the naming (e.g. that Jira sub-tasks correlate to VSTS tasks), but also in semantics as they relate to process template workflow (and UI support). We’re missing a Jira equivalent for VSTS’ features, and both Jira stories and tasks can be considered a VSTS product backlog item.

A few questions to keep in mind:

Does your team plan to use portfolio management functionality in VSTS? How many levels of backlogs do you need? Do you need to differentiate between Jira Story and Task?

State differences

The implementations differs further when it comes to states:

Jira stats

VSTS task states

VSTS PBI states

The VSTS task states are similar enough to Jira states, but what about PBI states? To Do might correspond both to New and Approved, and In Progress might correspond both to Approved and Committed. This semantical difference might not be resolvable just by mapping state names. You also need to review the sprints for stories, tasks and sub-tasks that are In Progress.

Additionally, you need to know if the Jira template has been modified with additional states. If so, what are they used for? Is there VSTS equivalent? The answer to the latter might be an equivalent state or an entirely different approach (for example, using VSTS test cases instead of Ready for Testing state).

The two tools also handle linking differently. What may be an Epic Link and Parent field in Jira is both replaced with Parent and Child link types in VSTS. A few link types typically found in Jira are missing also by default in VSTS, such as Blocked by and Caused by.

Customizations Of course, VSTS process templates can be heavily customized to resemble Jira. At some point, the problem becomes striking a balance regarding familiarity versus utilizing the new tool to full extent. In general, this means accepting some of the default idioms VSTS offer.

The first order of business in a Jira to VSTS migration is to review and understand current practices (and what purpose they serve). When doing this, you need to have a good understanding of what VSTS brings to the table. You can then change your practices to make them better fit the new tool.

With this in mind we can choose the appropriate VSTS template and then decide if and how we want to customize it. After that, we define necessary mappings and transformations between Jira and VSTS entities/names/values.

Primarily, in the basic scenario, we are looking at how to map:

  1. Issue types
  2. Link types
  3. States
  4. Measure fields (e.g. priority, story points, effort, remaining work)
  5. Backlog organization, such as sprint assignments and prioritization

Jira to VSTS implementation

Luckily, both Jira and VSTS offer APIs that we can build upon to automate the process.

In our experience, the biggest challenge when moving from Jira to VSTS is restoring and simulating history. Jira lets you access changes in fields, links and attachments, which together with API endpoint for accessing comments lets us create a change-by-change simulation of the history of an item.


Restoring the history and simulating the changes in this way presents couple of challenges:

  • We must ignore he rules VSTS enforces (API option) to be able to apply changes and impersonate another user. This has subtle effects on how well the tool will recognize these little cheats when presenting them in UI or in reports. Because the supported workflow rules aren’t always the same, this becomes extra important.

  • Attachments and other artifacts from past changes may no longer be available

  • Jira uses different API to access rendered fields. This means we’re able to simulate changes to this fields, but only the latest state will be rendered as in Jira.

If there are links to external artifacts, these need to be accessible from VSTS to have the same level of UI integration. If you have a link to a Bitbucket git repo commit, you also need to migrate the repo itself to VSTS if you want link to it from a migrated Work Item. Otherwise, it’s just plain text (which might be an acceptable compromise)

  • Expect to trigger changes in some fields when changing other fields (State and Reason fields come to mind). These can become complex to simulate considering possible permutations of changes.


Despite the challenges and some compromises, you can achieve decent fidelity when migrating from Jira to VSTS. One way is by isolating the migrated items from the rest of the project by using Areas at first. This enables some manual bulk editing and partial or iterative migration of the project data. However, the biggest challenge isn’t migrating data itself, but rather the adjustments in teams’ process tracking workflow.

If you want to perform the migration yourself, simply follow the procedure above. If you find yourself in trouble or facing challenges, don’t be afraid to contact us. We at Solidify have expertise and knowledge of both systems and would gladly help you out.

Which system are you working with? Have you considered migrating from one system to the other? Let us know in the comments below!