Item types

Open

1. Click the Jira field and select or enter an item type from Jira’s list.

2. Click the Azure field and select or enter a corresponding ADO work item type.
   TFS4JIRA can map item types automatically as default item types. When defined, the most common default item types are Task and Epic.

   Open

   

3. Click Add mapping to save your configuration.
   Mapped item types appear in the Mapped item types list.

   Open

   

4. Edit mappings.
   To modify a mapped item type, locate the item type in the Mapped item types list, click on the Jira or Azure item type, and select another item type from the dropdown list.

5. To remove a mapped item type, locate the item type in the Mapped item types list and click the Remove mapping icon.

Set how TFS4JIRA responds during synchronization when it encounters an unmapped item type.

• Skip - When TFS4JIRA encounters an unmapped item type, does not synchronize items of that type and moves on to synchronize the next item type.

• Raise Error - When TFS4JIRA encounters an unmapped item type, it is recognized as an error. You can review the error in the sync log.

• Set Item - When TFS4JIRA encounters an unmapped item type, it maps it to a specific value. For example, if Task is selected, all unmapped item types are mapped as tasks.

1. Click the Jira field and select Skip, Raise Error, or Set Item from the list of options. If you select Set Item, click the field below and select a value.

2. Click the Azure field and select Skip, Raise Error, or Set Item from the list of options. If you select Set Item, click the field below and select a value.

3. If you don’t want to enable Hierarchy, click Save settings and go to Fields.

Jira and ADO structure their work items differently. Jira has a more rigid hierarchy, such as Epic >Task/ Story/Bug (and other)> Subtask, while ADO allows parent-child relationships between various item types. With hierarchy mapping enabled, you can synchronize the items and relation links between issues across both platforms.

Hierarchy mapping ensures that relation links between items—such as tasks and their parent epics—are maintained across both systems. Without it, these links can be lost, making it hard to track work dependencies.

To enable hierarchy mapping, you need to Configure item types first. TFS4JIRA can synchronize relation links between items only if the items are already mapped between Jira and ADO. Make sure you have mapped all wanted item types.

There are some item types that you can’t synchronize without enabling hierarchy mapping, such as subtasks. Subtasks in Jira are always linked to a parent item and can’t be created without one. When mapping subtasks, you must choose other item types to enable hierarchy. If you don’t map all item types that are subtask parents, the subtasks can be created in ADO with missing parent links.

There are several scenarios you can follow for mapping item hierarchy depending on the needs and complexity of your project:

1. Hierarchy off - Mapping item hierarchy is optional. If you don’t enable hierarchy mapping, only individual item types synchronize. For example, if you map Epics and Stories, the Epic and its related Stories synchronize as standalone items, but the relation links between them (indicating that the stories belong to the epic) aren’t carried over. Subtasks won’t synchronize at all.
   Use Case: Configuring synchronization without hierarchy mapping is suitable for teams that only need to synchronize specific epics or tasks independently, without their relation links.

2. Hierarchy on, Epics mapped

   Open

   

   
   Epics and their relation links synchronize, meaning Epic-Story or Epic-Task relationships are reflected on both platforms.
   Use Case: This is useful for teams managing Epics and their related Tasks, ensuring the entire work structure stays in sync.
   
   

   Open

   

3. Hierarchy on, Epics and Subtasks Mapped

   Open

   

   
   Subtasks, along with their parent items and relation links, are synchronized. This means you can see detailed Task breakdowns remain intact.

   Use Case: Enable this if your teams work with detailed task hierarchies and need visibility into every level of work, from Epic to the smallest Subtask, and want to preserve relation links across both platforms.

   Open

   

The custom setup enables customized hierarchy synchronization, which supports synchronizing relation links for non-standard parent-child relationships between Jira and ADO.

The Custom setup option is available only after you enable the Hierarchy option. Therefore, all relation links between mapped item types are synchronized by default, as explained in the Hierarchy section. Additionally, you can map and synchronize non-standard parent-child relation links between Jira and ADO as you define them.

Use Case: Suppose your team uses a four-level hierarchy in ADO, which includes Epic > User story > Task > Issue. However, Jira only supports three hierarchy levels: Epic > Story/Task > Subtask. You can use the custom setup to synchronize all relation links while respecting Jira's hierarchy limitations.

1. Map the item types: Epics, Stories, Tasks, and Subtasks.

2. Enable the Hierarchy option to synchronize relation links supported by Jira.

   Open

   

3. Select the Jira link type from the In Jira field to map with the Parent/Child relation in Azure and allow relation link synchronization between Story and Task that Jira doesn’t natively support.

4. Click Save settings.
   
   

Open

Jira link types depend on the configuration in your Jira instance. TFS4JIRA retrieves the link types as they are defined in your environment.

For example, when the blocks link type is added in Jira, there is a Parent/Child link in Azure between the corresponding User Story and Task.

When the Parent/Child link is created in Azure, a blocks link is added in Jira between the corresponding User Story and Tasks.

If you disable the Hierarchy option but would like to map other link types, go to Links. Note that the relation links you define in the Custom setup under Hierarchy won’t be visible for the Links configuration as the Custom setup has a higher priority over Links.

Next steps

Go to Fields configuration.