Jira Align and Azure DevOps Integration: Best Practices

[#1]

Before integrating Azure DevOps with Jira Align, there are some best practices that should be considered. Some are a little more rigid than others; while others can lend themselves to some workarounds. Let's explore further to understand what these are, why these are important and the potential impacts. 

Projects

Support Multiple Projects

On/Off Toggle. If a Connector is setup for a Single project, then it cannot later be changed. The recommendation is always to set for On for Multiple Projects, even if there is only 1 single project.

Process Template Name

All projects that are synced via this Connector must use the same Process Template (see Band 2.1 Training for more information on process templates).
If projects with different process templates need to be synced then setup a connector for each process template type.

Project Setup

The ADO projects to be synced must be listed here. Check spelling and spaces/hyphens etc. Remember to click on the “+” sign.

Program Mapping

Each ADO Project can be mapped to an existing Jira Align Program.

Have a more complex environment?

An ADO project can (and usually does) hold more than one program. As evidenced by their Area path representing more than one program.
While the Microsoft guidance is that a project in Azure DevOps is similar to a portfolio in Jira Align, it isn’t necessary for the connector to be that strict.
If the ADO Project looks like a Portfolio, then you may have Area paths that look like:
ADO Project 1\Program 1
ADO Project 1\Program 2
These are what should be added into the ADO Connector with the Jira Align Program mapped.

Sometimes you might see:
Project 1\business unit x\subgroup charlie\portfolio alpha\program 1
as the Program level is further “down”.
This setting expects the full path to be listed under “Azure DevOps Value”

Work Code field name: (Optional) This is the name of the ADO custom field that is being used for Work Codes. It’s not a default field in an ADO Process Template work item.

Area Path Setup

In ADO, Teams contain the people and are then mapped to ADO Areas. The ADO Area path represents the organizational structure.

For synchronising with Jira Align, the ADO Area Path is what is relevant.

ADO Area names are what sync into Jira Align team names. This can be confusing, as the assumption is that it’s the ADO Team name that would sync with the JA Team.

The ADO Team members do NOT sync into Jira Align. Whoever is assigned to an ADO work item will get synced into Jira Align.

To summarise

1. ADO Area Name → becomes the name of the Jira Align team

2. ADO work item assignees → Jira Align work item assignees

ADO Area names are what sync into Jira Align teams. ADO Work item assignees are what sync to Jira Align work items.

The ADO Team object is NOT used by the ADO Connector.

It’s important to take note of the hierarchy of the Areas in order to configure the ADO Connector. The levels of ADO Areas that you wish to sync over into Jira Align will be needed to configure the minimum and maximum levels. A simple configuration should have all the ADO Areas at the same hierarchical level, and so the minimum and maximum will be the same (in the example, below it would be 3). More complex scenarios may need more than one level of ADO Area synchronised.

Proceed with caution. The ADO connector will NOT create the teams in a hierarchy in Jira Align, so manual post-configuration may be required.

Example of ADO Area-Level Mapping

In this scenario, the minimum AND maximum level would be 3

Scope Path: Only available when “Support Multiple Projects” is set to “Off”. This allows specific path synchronization.

Exclude Paths (Optional) - For excluding Area paths from synchronization

Iteration Path Setup

Program Increment Level Mapping: This setting is for the level that the Program Increments are set up. In a simple configuration, this should be the 2nd-lowest hierarchical level in the ADO Iteration Paths. The minimum and maximum level number should be the same (in the example below, this is set to 3). Iteration Path setup should follow the Microsoft recommended approach and be consistent across the ADO project. More complex scenarios can have different minimum and maximum levels.

Proceed with caution. If the min and max levels are set to different levels, the ADO connector will NOT create the program increments in a hierarchy in Jira Align, so manual post-configuration may be required.

Iteration Level Mapping: This setting is for the level that the Program Increments are set up. In a simple configuration, this should be the 2nd-lowest hierarchical level in the ADO Iteration Paths. The minimum and maximum level number should be the same (in the example below, this is set to 4). Iteration Path setup should follow the Microsoft recommended approach and be consistent across the ADO project. More complex scenarios can have different minimum and maximum levels.

Proceed with caution. If the min and max levels are set to different levels, the ADO connector will NOT create the sprints in a hierarchy in Jira Align, so manual post-configuration may be required.

Example of PI and Iteration Level Mapping

 

Buffer Days: The ADO Connector maps ADO iterations to JA Anchor Sprints based on the end dates of the iterations and sprints. Leave this setting empty for an exact match. Add buffer days eg +/- 1 days, if the JA sprint end dates don’t exactly match the ADO iteration end dates.

Adding buffer days here can cause sprint misalignment or non-synchronization. If the ADO Connector does not know which JA sprint the ADO iteration should be matched with then work items will not sync. The best practice is to ensure that the JA Anchor sprint end dates are identical to the ADO iteration end dates.

Scope Path: Only available when “Support Multiple Projects” is set to “Off”. This allows specific path synchronization.

Exclude Paths (Optional) - For excluding Iteration paths from synchronization