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

Spartez Software has joined the Appfire family. Learn more

TFS4JIRA - Hierarchy support is finally here

Agnieszka Józwiak
Agnieszka Józwiak
Aug 21st, 2018

Imagine the scenario, where you have your own structure in a project, where bigger issues are divided into smaller ones and those smaller ones are divided into even smaller ones.

Now, you need to migrate to a completely new system and even though you are using advanced migrating/syncing software like TFS4JIRA you cannot migrate the hierarchy.

To somehow save the structure you had, you're using labels or even brackets in task titles.

So much strange things to think about.

Those times are over.

Please welcome hierarchy synchronisation in TFS4JIRA.

What is hierarchy and are the differences between hierarchy in TFS/VSTS and Jira?

In this case, hierarchy means dependency (tree structure - one issue is splitted in to smaller ones, those smaller ones can be than splitted to even smaller, more detailed tasks).

How it is defined in Jira?

According to Jira documentation, Jira Software does not explicitly offer sub-projects, but it is possible to structure project in a way that it represents the hierarchy you need.

Within Jira Software projects, you can add multiple epics, which can act as a "sub-project" that can be divided into stories/tasks and sub-tasks.

The default hierarchy contains:

  • Epics - Once the higher level priorities are settled it's necessary to break them down into large pieces of work, which consist of multiple stories.
  • Stories/Tasks - User stories capture functionality requirements.
  • Sub-task - Work components that make up stories. So by default you can use 3 different levels.

In Team Foundation Server / Visual Studio Team Services you can have as many levels as you want, which makes the whole project much more complex.

In the following screen, you can see a project that has 4 levels - epic, product backlog item, task and a subtask.

On Microsoft VSTS documentation, you can find an example of even more complicated structure - epic, feature, product backlog item, bug and task.

So it means, you have... 5 different levels.

How we sync / migrate one structure to the other?

Now we know that both applications have different hierarchy levels, so how do we migrate a project from TFS to Jira without breaking the current project structure knowing that, by default, Jira has 3 hierarchy levels?

You can either preserve the current TFS project structure, which basically means mirror the structure in both sides, or choose what part of the tree structure you want to synchronize between both applications.

We created the following diagram to help you visualize how to match hierarchy levels between TFS and Jira.

How can it be used in practice? Map the structure as follows:

  • Epic with Epic,
  • Feature in TFS with custom issue type in Jira - call it Feature as well,
  • User story with Story,
  • Task with Sub - task,
  • Create link in Jira between custom issue Feature and Story. This link will be translated to TFS Parent/ Child link during synchronization.

Another way is to choose just 3 levels from TFS that you'd like to preserve (so the lowest or the highest level won't be synced).
For example:

How to set it up on TFS4JIRA?

Follow our documentation for detailed guide through setting up the TFS4JIRA synchronizer.


TFS4JIRA 7.3 release, with hierarchy mapping is a big milestone for the product. Our public roadmap , which was formed based on customer feedback was aiming till this moment.

We hope that now TFS4JIRA will be even more useful and will help you in migrating from TFS/VSTS to Jira or vice versa even more effectively - same goes with synchronization.

Do you want to schedule a demo? Do you have a question or a feature request?

Let us know at