Azure DevOps integration data mapping

The following diagram illustrates the general scheme of field mappings for mapping a Azure DevOps project to a Jira Align program.

Additional diagrams for team and portfolio mappings are located in the Appendix.

State mapping and state movement restrictions

Jira Align allows a transition to/from any state. Azure DevOps, on the other hand, can implement state transition rules about which states can be targeted from source states, and about fields that might be conditionally required. For example, if there have been defined some state transition rules that the Jira Align application violates, this can cause unexpected behavior related to replication.

Consider the following scenario:

A Product Manager moves a feature in Jira Align from state A to state B, and the connector attempts to replicate this in Azure DevOps. Azure DevOps doesn’t allow this transition, so the state transition is rejected, but no message is sent to the user. Later, when the Jira Align connector discovers the feature with state A with Jira Align out of sync, it returns the feature in Jira Align to its prior state, state A. A Product Manager will discover that the feature returned to its prior state on the next screen refresh.

In Progress state roll-ups

Moving work that has not begun to the In Progress state will roll-up in Jira Align between related stories and features. When allowed, these changes will also sync to Azure DevOps.

For example, consider a story that has an associated feature. Both work items are in a Not Started state. When the story is changed to the In Progress state, the change rolls-up to the associated feature. If the story in this example is moved from In Progress backwards to Not Started, the feature remains in the In Progress state.

These roll-ups only take place up from child items to their parents. For example, changing a feature from Not Started to In Progress will not affect any associated stories. The audit log for a work item will indicate when edits or roll-ups take place.

Work items

When you create a feature, story, or defect in Jira Align and select a mapped program, a new field will display — Azure DevOps Area Path. Select the Azure DevOps area path that represents your program in the field in order for the work item to sync. You will also need to specify a team in Jira Align for the work item to sync to the team-level area path in ADO.

When you create a work item in Azure DevOps, the connector will map the item to the correct program in Jira Align, based on your configuration settings. The Azure DevOps Area Path field will be set and displayed as read-only in Jira Align. 

Moving a work item in either Azure DevOps or Jira Align affects these fields as well. When you move a work item into a different program-level area path in ADO, the Azure DevOps Area Path field will update in Jira Align upon the next sync. We recommend moving synced items in ADO instead of Jira Align to maintain or properly change mapped programs and area paths.

When you cancel a work item in Jira Align, the synced item in ADO will be marked as deleted and can be found in the Recycle Bin.

Field mappings

The following tables detail how data is mapped between Jira Align and Azure DevOps for each of the integrated objects represented in the data mapping diagram above. In addition to the fields below, all work items copied into Jira Align will have a field for External ID set to the Azure DevOps’ key.

Azure DevOps features become features in Jira Align

Jira Align Field | Azure DevOps Field

Create

Update

JA to Azure DevOps

Azure DevOps to JA

JA to Azure DevOps

Azure DevOps to JA

Name | Title

Yes

Yes

Yes

Yes

Description | Description

Yes

Yes

Yes

Yes

Tags | Tags

Yes

Yes

Yes

Yes

Owner | Assigned To

Yes

Yes

Yes

Yes

Status | State

(Mapped via configuration setting)

Yes

Yes

Yes

Yes

Program Increment | Iteration Path

(Mapped via end date)

Yes

Yes

Yes

Yes

Program | Area Path

(Mapped via configuration setting)

Yes

Yes

Yes

Yes

Start/Initiation Date | Start Date

Yes

Yes

Yes

Yes

Target Completion Date | Target Date

Yes

Yes

Yes

Yes

Capitalized | <Custom Field>

Yes

Yes

Yes

Yes

Type

Yes

Yes

Yes

Yes

Product | <Custom Field>

Yes

Yes

Yes

Yes

Acceptance Criteria | <Custom Field>*

(Mapped via configuration setting)

Yes

Yes

Yes

Yes

Custom text input fields | <Custom Field>

(Mapped via configuration setting)

Yes

Yes

Yes

Yes

Custom single-select dropdown fields | <Custom Field>

(Mapped via configuration setting)

Yes

Yes

Yes

Yes

Custom text area fields | <Custom Field>

(Mapped via configuration setting)

Yes

Yes

Yes

Yes

* In programs that sync with ADO, you’ll be limited to a single acceptance criteria text field in Jira Align since the default ADO acceptance criteria is a text field. If you already have multiple acceptance criteria in Jira Align for work items in these programs, the connector will automatically merge them into a single, formatted text field.

Azure DevOps stories and configured work item types* become stories in Jira Align

Jira Align Field | Azure DevOps Field

Create

Update

JA to Azure DevOps

Azure DevOps to JA

JA to Azure DevOps

Azure DevOps to JA

Name | Title

Yes

Yes

Yes

Yes

Description | Description

Yes

Yes

Yes

Yes

Estimate (Points) | StoryPoints or Effort or Size

(Depending on template)

Yes

Yes

Yes

Yes

Team | Area Path

(Case-sensitive name match)

Yes

Yes

Yes

Yes

Sprint | Iteration Path

(Mapped via end date)

Yes

Yes

Yes

Yes

Parent Feature | Parent Link

Yes

Yes

Yes

Yes

Owner | Assigned To

Yes

Yes

Yes

Yes

Status | State

(Mapped via configuration setting)

Yes

Yes

Yes

Yes

Program Increment | Area Path

(Mapped via end date)

Yes

Yes

Yes

Yes

Program | Area Path

(Mapped via configuration setting)

Yes

Yes

Yes

Yes

Tags | Tags

Yes

Yes

Yes

Yes

Type | Value Area

(Mapped via configuration setting)

Yes

Yes

Yes

Yes

Acceptance Criteria | <Custom Field>**

(Mapped via configuration setting)

Yes

Yes

Yes

Yes

Custom text input fields | <Custom Field>

(Mapped via configuration setting)

Yes

Yes

Yes

Yes

Custom single-select dropdown fields | <Custom Field>

(Mapped via configuration setting)

Yes

Yes

Yes

Yes

Custom text area fields | <Custom Field>

(Mapped via configuration setting)

Yes

Yes

Yes

Yes

* Azure DevOps work item type Stories = Product Backlog Item in the Scrum process template, User Story in the Agile process template, and Requirement in the CMMI process template.

** In programs that sync with ADO, you’ll be limited to a single acceptance criteria text field in Jira Align since the default ADO acceptance criteria is a text field. If you already have multiple acceptance criteria in Jira Align for work items in these programs, the connector will automatically merge them into a single, formatted text field.

 

Azure DevOps bugs become defects in Jira Align

Jira Align Field | Azure DevOps Field

Create

Update

JA to Azure DevOps

Azure DevOps to JA

JA to Azure DevOps

Azure DevOps to JA

Name | Title

Yes

Yes

Yes

Yes

Description | System Info

Yes 

Yes

Yes 

Yes

Parent Story | Parent Link

Yes 

Yes

Yes 

Yes

Team | Area Path

Yes 

Yes

Yes 

Yes

Sprint | Iteration Path

Yes 

Yes

Yes 

Yes

Owner | Assigned To

Yes 

Yes

Yes 

Yes

Status

No

Yes

No

Yes

Program Increment | Iteration Path

Yes 

Yes

Yes 

Yes

Program | Area Path

Yes

Yes

Yes

Yes

State | State

(Mapped via configuration setting)
Yes Yes Yes Yes
Priority | Priority Yes Yes Yes Yes
Severity | Severity

(Mapped via configuration setting)
Yes Yes Yes Yes
Steps to Reproduce | Repro Steps Yes Yes Yes Yes
Tags | Tags Yes Yes Yes Yes
Estimate (Points) | Story Points Yes Yes Yes Yes
Estimate (Hours) | Original Estimate Yes Yes Yes Yes
Remaining | Remaining Yes Yes Yes Yes

 In addition, when a defect in Jira Align is set to a state that maps to Closed in Azure DevOps, the Closed By field of the bug in Azure DevOps is set to the owner of the Jira Align defect; when a bug in Azure DevOps is closed, the Fixed By field of the Jira Align defect is set to the Azure DevOps Resolved By user.

If the Jira Align defect’s State field changes to Fixed, the connector will also change its Status to Closed.

Azure DevOps tasks become tasks under Jira Align stories
(tasks only synchronize from Azure DevOps into Jira Align)

Jira Align Field | Azure DevOps Field

Create

Update

Azure DevOps to JA

Azure DevOps to JA

Name | Title

Yes

Yes

Description | Description

Yes

Yes

Effort (Hours) | Original Estimate

Yes

Yes

Owner | Assigned To

Yes

Yes

Status | State

(Mapped via configuration setting)

Yes

Yes

Parent Story | Parent Link

Yes

Yes

 

Agile Teams

For each area path that matches the level set in the configuration to represent teams, the connector will attempt to find an Agile Team with a name that matches exactly (including case and spaces).  If the connector cannot find a matching team, it will create one. If teams don’t yet exist, we recommend letting the connector create the teams for you, so that you don’t have to worry about matching names.

Note: if the connector finds a team with the same name but under a different program, it will move the team.

Users are added to teams in Jira Align when the user is added as the assignee of a story, defect, or child task that is assigned to a team and a sprint.

Automatic user creation and team assignments

Users may be created and added to a team in Jira Align automatically, based on their association with a work item in Azure DevOps. The following rules apply:

  • When an Azure DevOps user creates or updates a synced story, defect, or child task, a matching user — if not present — is created in Jira Align.
    • The new user is not added to a team in Jira Align.
  • When an Azure DevOps user is added as an Assignee to a synced story, defect, or child task that is assigned to a team, a matching user — if not present — is created and added to the matching Jira Align team.
    • If the user already exists in Jira Align, they are added to the matching team.
    • Users added to a Jira Align team are given the role of Developer.
    • Team membership for tasks is determined through the team associated with the parent story in ADO.
    • Team allocations are not set in Jira Align for agile teams.
    • Team allocations are set to 100% for tasks and defects in Jira Align for Kanban teams.
    • When team assignment changes for a work item in ADO, team members are not removed from the previous team in Jira Align.

Time increments

A program increment in Jira Align matches with an Iteration Path in Azure DevOps, where the iteration path is at the number of levels of hierarchy identified in the connector configuration setting and the Iteration Path has an end date that matches the end date of the Jira Align program increment. It is possible for the connector administrator to set a number of buffer days to allow the match to be fuzzy.

A sprint in Jira Align is created automatically by the connector for each program’s Agile Team for Azure DevOps iteration paths where:

  • The iteration path is at the number of levels of hierarchy identified in the connector configuration setting
  • The iteration path is below an iteration path that has automatically mapped to a program increment in Jira Align
  • There is a sync sprint defined in Jira Align at the program increment that matches the end date
  • A team exists within the appropriate program

For example, the iteration path /project/2019/pi-1/sprint 7 will only create a team sprint if /project/2019/pi-1 maps to a program increment in Jira Align and that program increment has a sync sprint with an end date that will map to the full iteration path’s end date.  The team sprint name in Jira Align will be created or changed to the same name.

When work items are copied from Azure DevOps, the iteration and program increment will be set based on finding those that match the iteration path’s date criteria as above.  It is possible for a work item to be in an iteration path that is below the defined levels and the connector will still map it properly.  For example, a feature in /project/2019/pi-1/sprint 7 will still be placed in the program increment pi-1 if the program increment level is set to 3, and a story in /project/2019/pi-1/sprint 7/sprintlet a/monday would still find its way to the program increment related to pi-1 and the sprint related to sprint 7 if the sprint level is set to 4.

Note: The count of levels for iteration paths and for area paths always includes the root (which is the project name in Azure DevOps), so /project/21stc/2019/H1/Q2/sprint 2.3 is at level 6.

Users are assigned to sprints in Jira Align when the user is added as the assignee of a story, defect, or child task that is assigned to a team and a sprint.

Notes:

  • Sprint assignments for tasks are determined by the parent story's iteration path.
  • The connector does not remove users from sprints; it only adds them.

Assessment tables: document your Azure DevOps hierarchies

The following tables show examples of how you might have Azure DevOps configured for a portfolio, program, and team; the tables also contain blank cells for you to pencil in a sampling of your hierarchies. Please examine your Azure DevOps hierarchy during this exercise and write down your configuration to help us understand how it is structured and what levels are represented. It may be beneficial to collaborate with your Jira Align Solutions Architect for these exercises.

Team area hierarchy

If multiple portfolios exist, capture each one and set up a separate project connector for each.

Level #

Portfolio level example

Your configuration

1

Portfolio  

2

Program  

3

Team  

 

Iteration hierarchy

Level #

Portfolio level example

Your configuration

1

Fiscal Year  

3

Program Increment  

4

Sprint  

 

Work item hierarchy

Level #

Portfolio level example

Your configuration

1

Feature  

2

Story  

3

Task  

 

Was this article helpful?
0 out of 0 found this helpful
Print Friendly Version of this pagePrint Get a PDF version of this webpagePDF

Join the Atlassian Community!

The Atlassian Community is a unique, highly collaborative space where customers and Atlassians come together. Ask questions and get answers, start discussions, and collaborate with thousands of other Jira Align customers. Visit the Jira Align Community Collection today.

Need to contact Jira Align Support? Please open a support request.