This tutorial is for Jira Datacentre and Server without Advanced Roadmaps. If you are uisng Jira Cloud or do have Advanced Roadmaps, before proceeding, please review this article.
Even if you are connecting to a Cloud instance, this tutorial may help you better understand how the hierarchycal mappings work. It cannot be used as it is to configure the product in your situation, though.
We are going to implement the following scenario:
A task structure is created in MS Project. The first level of the hierarchy should be represented as Epics in JIRA. The second level will be Stories. Under the stories we are creating a varying number task levels.
The project is published in JIRA.
Team members may split the tasks (issues) on the last level further by creating sub-tasks.
The project manager imports the new sub-tasks from JIRA into the existing structure in MS Project.
The project plan we are starting with looks as follows:
First, we will need to configure the synchronisation mappings.
In addition to entering the regular settings, do the following:
Tick Populate Epic Name. This will set the Epic Name field, which is mandatory, to the same value as Summary.
Select the Task Name option. We will not need the composite issue names because we are setting up a hierarchy in JIRA.
Map Issue Type to a text custom field as we will need to create issues of different types and define filters based on this field.
Now we will need to configure the mappings that determine the issue hierarchy - Epic Link, Issue Link and Sub-task mappings. Each of these mappings must be applied to a particular group of issues/tasks so that no other mapping is applied to the group. If this rule is not observed, that is if there is more than one hierarchical mapping applied to the same issue, synchronisation will not work the way we want it to because the mappings will compete for the place of the issue in the hierarchy.
We will use issue type filters to split issues/tasks into the groups and Outline Level conditions to divide the issues of the same type further by their hierarchy level in Microsoft Project. The issue type filters select issues by their type in JIRA if the data is coming from JIRA into MS Project or using the value from the MS Project field mapped to Issue Type if data is copied from MS Project to JIRA.
Create a mapping for the parent-child link in JIRA (you will need to add this link if it does not exist).
Select the link and the end of the link to be mapped. The link type 'Hierarchy' in the screenshot is just an example. You need to select from the dropdown list a link type available in your JIRA.
Tick the Parent mapping mode.
Set the From level to 3. This is required to prevent Ceptah Bridge from creating links from the 2-nd level issues to the 1-st level issues, which will be Epics and should be linked to using Epic links instead.
Tick Only for these issue types and select all types except Epic and Sub-task. We need to exclude sub-tasks as they will have their own reference to the parent. Excluding Epics does not make any difference in practice, but we are during that just for the filter to make more sense.
Set the direction from JIRA to MS Project so that if a sub-task is moved under a different parent, this change will be reflected in MS Project.
Tick Only for these issue types and select 'Sub-task'. That mapping should be applied only to sub-tasks. If we apply it to all tasks, during synchronisation they will be moved on the first level if they are not linked to sub-task issues, which may be desirable in other cases, but not in ours.
Turn the Epic Link mapping on.
Select the Parent mapping mode.
Set the level selector to 2..2. That will ensure that only the issues linked to MS Project tasks on the 2-nd level are included into Epics.
Tick Only for these issue types and select all types except Epic and Sub-task. We need to exclude sub-tasks because we do not want redundant epic links to be created for sub-tasks on the second level. Similar to the Links mapping, excluding Epics does not make any difference in practice, but we are not including them for the sake of common sense.
After we have saved the settings, the mapped fields will be added to the current view. Enter issue type for the tasks whose linked issues should have a non-default type in JIRA in the Issue Type (Text3) field in MS Project.
Once synchronisation has been run, new issues reflecting the task hierarchy from Microsoft project will be created in JIRA.
Now the assignee of the Implementation task (stieve) splits it into sub-tasks in JIRA.
Let's import these new sub-tasks into MS Project.
We need to provide criteria for selecting the issues originating from our project and tick Import Subtasks to make sure that all sub-tasks under them are imported.
Press Import to detect the changes.
After we have applied the changes, new tasks representing the additional decomposition created in JIRA will be placed under the Implementation task.
