Mapping States, Steps, and Statuses between Jira Align and Jira Software

[#1]

Objective

Configure Jira Align to allow issue state transitions made in Jira Software to be reflected as desired in Jira Align and vice-versa.

Prerequisites

• Jira Software integration is in place and issues are syncing with Jira Align bidirectionally

• Jira Align Value Stream defines Backlog Process Steps

Background

It is important that Program and Portfolio users of Jira Align and Teams using Jira Software have a consistent view of work item status. For example, your business process may work as follows:

• Program Team using Jira Align moves a Feature into the “Backlog” column on the Program Backlog Process Step view to reflect that it is ready for work.

• Teams using Jira Software see that the corresponding Jira Epic is ready for work and update the Epic status to “Implementing” as they begin their work.

• The Program Team sees the progress of the Feature through implementation and delivery steps in Jira Align.

• Jira Align reports roll up results across many Programs using standard Jira Align states that have been automatically updated along the way.

Jira Align offers two ways to manage the state of an issue, both of which can be mapped to corresponding Jira Software issue statuses:

1. Jira Align State: Default, non-customizable, system-defined statuses

2. Jira Align Value Stream Process Step: Configurable, user-defined custom steps

Description

Choose the direction of mapping desired and follow the corresponding path number and color in the below instructions.

1. (PINK PATH) Jira Software Status to Jira Align State

1. Navigate to Jira Administration>Jira Settings>State Mapping

2. Select Feature (or another Jira Align issue type that syncs with Jira Software) from the Type dropdown to see a list of statuses in available Jira Projects

3. Select one of the out of the box Jira Align States from the dropdown for each Jira State that is used

4. Click Save to cause the Jira Align State to be automatically updated when the Status on the corresponding Jira Software issue is changed

Note: The first Jira Align State, “0 - Pending Approval” for Features and Stories, is the default value. Reset fields to this default value to remove a previously set mapping.

         

2. (PURPLE PATH) Jira Align State to Jira Software Status

1. Navigate to Jira Administration>Jira Settings>Manage Projects

2. Click State Mapping for the desired Project

3. Select Feature (or another Jira Align issue type that syncs with Jira Software) from the dropdown to see the list of out of the box Jira Align states
4. Select one of the Jira States within the selected Jira Project for each Jira Align State
5. Click Update to cause the Jira Software issue status to be automatically updated when the State on the corresponding Jira Align issue is changed

         

IMPORTANT:  For a given Project, only one mapping method can be used. State or Process Step. When you select one of these methods in the dialog, it is highlighted in green and takes effect immediately. Make sure the desired method is selected (highlighted in green) before closing the mapping dialog. The method highlighted in green when the dialog is closed will be the one that is used by the Connector.

---

3. (DARK BLUE PATH) Jira Software Status to Jira Align Process Step

1. Navigate to Jira Administration>Jira Settings>Manage Projects

2. Click Manage Custom Fields

3. Select work item hierarchy Level in the first section called Sync Process Steps with Jira States

4. Select Value Stream which was used to define the Jira Align Process Steps to see a list of statuses available in Jira Projects

5. Select one of the Process Steps for each Jira Status that is used

6. Click Update Steps to cause the Process Step of the Jira Align issue to be automatically updated when the corresponding Jira Software Issue is changed

         

4. (LIGHT BLUE PATH) Jira Align Process Step to Jira Software Status

1. Navigate to Jira Administration>Jira Settings>Manage Projects

2. Click State Mapping for the desired Project

3. Click Process Step
4. Select Process Steps level (e.g. Feature)
5. For each Process Step, select the corresponding Jira State (Jira Software Status)
6. Click Update

Note: Currently, this mapping must be enabled with a feature toggle by Jira Align Support or Services.

Note: For all the Projects you configure Jira Align to Jira Developmental Process Step Mapping on you will need to default the Jira Align to Jira State Mapping to "Select One". If you fail to default the Jira Align to Jira State Mappings to "Select One" Statuses between the two applications will become out of sync.

Note: For all of the Programs that will sync Process Steps from Jira Align to Jira the "Developmental Process Step" field will need to be added to the corresponding work item screen under Jira Align Admin > Details Panel Settings.

         

IMPORTANT:  For a given Project, only one mapping method can be used. State or Process Step. When you select one of these methods in the dialog, it is highlighted in green and takes effect immediately. Make sure the desired method is selected (highlighted in green) before closing the mapping dialog. The method highlighted in green when the dialog is closed will be the one that is used by the Connector.

---

5. (GREEN PATH) Jira Align Process Step to Jira Align State

1. Navigate to Portfolio>Value Streams

2. Select the Value Stream to map for which Process Steps have been defined

3. Click the Map to State toggle

4. Select the Jira Align State which maps to each Process Step
5. Click Save to cause the Jira Align State for issues to be automatically updated when the Process Step of the issue is is changed

Note: This mapping is bidirectional and immediate, but only if updated In Jira Align. It has no effect if the Jira Align State or Process Step is modified by another Jira SW state mapping.

         

Output and Summary Notes

• Status updates for issues in Jira Software will be reflected in Jira Align states and process steps and vice-versa.

• Mapping Jira Align States or Process Steps and Jira Software Statuses in only one direction will result in confusing behavior.

• When an issue has been resolved in Jira Software, Jira Align updates will no longer have an effect in Jira Software and will be reverted in Jira Align.  The Resolution status must be cleared in Jira if such a change is desired.

• Update times are dependent upon the “Timer on Jira Issues” that has been configured on the Admin>Jira Settings>Jira Setup page.

Related Materials

• Atlassian Community Article, “How to Configure State Mappings between Jira Software and Jira Align”

• Atlassian Community Article, “Jira Connector - Changing the state on a Jira Align work item fails to sync the change to Jira”

• Jira Software Administration Support Document, “Working with workflows”

[bkrimsky]

Don, thank you for the explanation but no where in the document does it state that you can only map 6 states. is that wrong? can you map more than 6? if so, what is the max number of states allowed? if it is 6, why? why not 8? could you teach us what is the logic in the restriction please? 

thank you again for taking the time

[Sanwar Mal]

Yes,

I do not want to map to just 6 predefined states, is there a way to change JA states, add/remove etc?

I would be disappointed if answers comes as they are hardcoded.

[Colin Weaver]

Apologies for  a bit of a late answer for both the questions above, however they are still worth answering as others  may have the same questions.

The list of States in Jira Align is hard coded to 6.

If you want to use more than the provided 6 (or use different names) then this is where using a Process Flow and naming the Process Steps becomes the solution

In essence

• if using some (or all) of the default 6 Jira Align states, configure Paths 1 & 2
• if using Process Steps to customize the choices, then configure process flows for both Features and Stories in Jira Align and then configure Paths 1, 3, 4 & (usually) 5

[Heidi Hendry]

There's a reason that the 6 predefined states are hardcoded, and that is to force alignment.
So teams can have as many statuses as they want, but they all align back to the 6 hardcoded states. These states are then used in all the reporting.

This means that a Portfolio Owner or C-suite don't need to work out exactly what a team means by "In Beta" or "Refinement"  or "waiting for review" or any of the myriad status names I've seen in a Jira instance.

The interpretation work is done for them by the process step mapping.

[Colin Weaver]

As this Community article was written some time ago with screenshots and steps that were:

• from before the New Navigation was introduced
• from before we updated the operation and look of the configuration screen for the Jira Align Process Step to Jira Software Status path
• from before some fields/settings relating to the Jira Connector  were renamed 

we have updated it and migrated it to the the Jira Align Knowledgbase

At the same time we used the opportunity to clarify some points about the configuration that had not been covered in this original community article so the new version now discusses:

• When to use State Mappings and when to use Process Step Mappings (as well as a reminder on the fixed names of the States in Jira Align which is related to which mappings you may decide to use.)
• Details of which paths should usually be used with each other (against two different scenarios)

The new version can be found by using the below link:

https://confluence.atlassian.com/jakb/mapping-states-process-steps-and-statuses-between-jira-align-and-jira-software-1387599540.html 

Note: We could have arranged for this community article to be updated, however as only the author can adjust the content of the original community post but in our new KB system it is possible for other members of the support team to adjust the core content, we decided to migrate it in order to make any future changes easier to deal with.