TFS4JIRA - Map multiple fields to a single field

Owned by Michał Szymul
Last updated: Nov 14, 2024 by Mark Kleinsmith
2 min read

This article applies to:

  • TFS4JIRA Cloud

  • TFS4JIRA Self-hosted

Overview

TFS4JIRA lets you map multiple fields to a single field. In the Mapped Fields example below, Azure DevOp’s Description and Acceptance Criteria fields are both mapped to Jira’s Description field:

image-20240905-142140.png

What happens when multiple fields are mapped to a single field?

In the example above, the Description and Acceptance Criteria fields from Azure DevOps are mapped to the Description field in Jira. The mapping has the following characteristics:

  • There is a one-way synchronization from Azure DevOps to Jira, indicated by the single-direction arrow.

  • The Description field in Azure DevOps is the primary field.

With this setup, the value in the Azure DevOps Description field is synchronized with the Description field in Jira. However, if the work item in Azure DevOps uses the Acceptance Criteria field, its value will not be mapped as Jira’s Description. This is because only the Primary field in a multi-mapping scenario has read/write permissions. All other fields only have write permissions.

The example above illustrates one-way synchronization. With bi-directional synchronization enabled, the mapping displays as:

Jira Azure

Description ↔︎ Description (Primary)

→ Acceptance Criteria

In the bi-directional setup, synchronization from Azure DevOps to Jira works the same as the original, one-way synchronization example. However, while synchronizing from Jira to Azure DevOps, the synchronizer first checks if the Description field is available for the target work item. If not, it looks for the Acceptance Criteria field and adds the Jira Description there.

Recommendations

The most reliable synchronization solution is to define a unique link for each field.

However, if you cannot add new fields in either Jira or Azure DevOps, we recommend configuring a separate profile to synchronize each Issue and Work Item type.

For example, Acceptance Criteria are usually specific to the Bug work item type in Azure DevOps. Copy your existing synchronization profile and use it for Bug synchronization only. Therefore, you will be able to map Jira’s Description only to Azure DevOp’s Acceptance Criteria.