Mapping Jira Resolution to Azure DevOps ResolvedReason and Reason

Owned by spg bot
Last updated: Feb 01, 2023 by Roman Lutsiv [Appfire]
3 min read

Business Case

As a user I would like to synchronize Jira Resolution field with Azure DevOps Reason and ResolvedReason field so that I know why an issue / work item was closed.

Scope and known limitations

At the moment of writing Team-managed projects (formerly next-gen) have limited support[1] for Resolution field [2]. For this reason, here we will focus only on Company-managed projects.

On Azure DevOps side there are several process templates that differ in work item types, their statuses, fields and transitions [3].

For example, Basic process (by default) does not have a Bug type, and ResolvedReason field, while Agile does. For this reason, we will describe configuration for each process type separately.

Both Jira and Azure DevOps allow to update those fields after an issue / work item was closed. But, as of now, Syncrhonizer does not pick up changes in Resolution and ResolvedReason fields that occur outside of status transitions [4]. To work around that please:

Synchronizer does not support conditional many to one mappings, separate synchronization profiles are usually needed to map both ResolvedReason and Reason to resolution [5]

Understanding purpose and semantics

Make sure to review best practices for using Resolution field [2]

Jira Resolution field should be set only when issue is in it's "final" state [2] (aka JQL statusCategory=Done). Resolution field is available (by default) for all issue types, and is intended to be changed by the user. The purpose of this field is to provide more context as to "why is the issue closed".

Azure DevOps ResolvedReason serves a similar purpose, however, it only is available for Bug type (by default).

The rest of work item types usually have Reason field. Reason is usually updated automatically by the system [3] during status transition, and still, can be changed by the user. Reason explains why an issue is in it's current state.

Since Synchronizer does not support conditional many to one mappings, separate synchronization profiles are usually needed to map both ResolvedReason and Reason to resolution [5]

In Azure DevOps ResolvedReason is dependent on Reason field in several templates, including CMMI and Agile. This is implemented via process rules [6]. The effect is that changing Reason changes the allowed values for ResolvedReason , so sometimes the only valid mapping is to map both of these fields to Resolution - a specific example is Bug type in Agile.

In summary, Jira Resolution field should be

  • multi-mapped to (Reason ; ResolvedReason) for work item types that have both fields (like Bug)

  • single-mapped to Reason for fields that do not have a ResolvedReason (Task, Epic)

  • value mapping for Reason should only contain values for “final states”

Step by step instructions

Resources

[1] To learn more about limitations of Resolution in Team-managed projects, please refer to

[2] To learn more about the Resolution field in Jira see Best practices on using the "Resolution" field | Atlassian Cloud | Atlassian Documentation

[3] For an overview of processes in Azure DevOps see Choose a process for your Azure DevOps project - Azure Boards

[4] TFS-3315: As a synchronizer user I would like Synchronizer to pick up changes in Jira Resolution and TFS ResolvedReason that happen outside of state transitions, so that I can easily edit those fieldsTO DO

[5] TFS-3316: As a synchronizer user I would like to be able to configure many to one conditional value mapping so that I can avoid having multiple similar syncrhonization profilesTO DO

[6] Default rule reference - Azure DevOps