Summary

The article explains how to configure Jira Align to allow issue status transitions made in Jira Software to be reflected in Jira Align, as changes to states and / or process steps (and vice-versa).

It is an updated version of the information originally published as a Community (forum) article. To see the original please visit this link:

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

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.

Environment

Jira Align

Solution

Prerequisites

• The Jira Connector is configured to integrate with your Jira Software and work items / issues are able to sync with Jira Align bidirectionally

• The latest Jira Statuses have been pulled from Jira into Jira Align (if unsure, run Settings > Jira Settings > Resync Configuration > Configuration data pull )

• If intending to use Process Steps, suitable Process Flows (Value Streams) have been created in Jira Align (within Portfolio > select Portfolio > More Items > Process Flows )

• If intending to use Process Steps, the Process Step field has been added to the corresponding Jira Align work item screen (under Settings > Details Panel Settings ).

Configuration Steps

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

1. Jira Align States: Default, non-customizable, system-defined states

   The system-defined states are
   0 - Pending Approval
   1 - Ready to Start
   2 - In Progress
   3 - Dev Complete
   4 - Test Complete
   5 - Accepted

   • If customized state names are needed, then use Process Steps
   • If more than the 6 states are needed, then use Process Steps
   • If there are 6 (or less) Statuses in the Jira Workflow then Jira Align States can be used

   
   

2. Jira Align Process Steps: Configurable, user-defined custom steps

   • Jira Align States are still used in parallel with using Process Steps
   • Process Step names are customizable
   • More then 6 Process Steps can be configured
   • An exact match for the statuses in the Workflow of the Jira Project can be configured

Which method is being used then determines which of the paths provided below needs to be configured:

• If only using Jira Align States then configure: Path 1 (Pink Path) and Path 2 (Purple Path) 
• If using both Jira Align Process Steps and Jira Align States then configure: Path 1 (Pink Path), Path 3 (Dark Blue Path), Path 4 (Light Blue Path) and Path 5 (Green Path)

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

1. In Jira Align, go to Settings > Jira Settings > State Mapping (tab)

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. Make sure your workflow's Jira Statuses are shown in the "Select the Jira State you want to map to a Jira Align state" box (click on an empty space in the box to add them if not)

4. Select one of the, out of the box, Jira Align States from the dropdown for each Jira State that is used in your Jira Workflow

   1. if configuring the Story state mapping be aware that you cannot choose the 5 - Accepted JA state in this configuration. The Jira Status representing Done must be mapped to the JA State of 4 - Test Complete
      - see  How to map Jira 'Done' status to Jira Align 'Accepted' state for stories
   2. Feature mappings do allow 5 - Accepted to be configured.
   3. More than one Jira Status can be connected to the same Jira Align State 

5. Click Save 

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. In Jira Align, go to Settings > Jira Settings > Manage Projects

2. Click the State Mapping link at the end of the row for the desired Project

3. Make sure the toggle under Process steps mappings is disabled
4. Select Feature (or another Jira Align issue type that syncs with Jira Software) from the Work item type dropdown to see the list of out of the box Jira Align states
5. Select one of the Jira Statuses within the selected Jira Project for each Jira Align State. (If you have less Jira Statuses then Jira Align States, then you can configure the same Jira Status against more then one Jira Align State, however when doing this make sure that you match any many-to-one relationships configured in Path 1)
6. Changes are saved automatically, so click Close when all the required mappings have been set.

Path 2 (State Mapping) and Path 4 (Process Step Mapping) are mutually  exclusive, meaning you cannot configure both paths. Older versions of Jira Align used a pair of green tabs to choose between the two, however which Path was configured was defined by what was set when the last administrator closed the screen. To avoid accidental user error this was changed to the toggle.   

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

1. In Jira Align, go to Settings > Jira Settings > Manage Projects

2. Click Manage Custom Fields

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

4. Select the Process Flow which was used to define the Jira Align Process Steps (one of the prequisites) to see a configurable list of mappings for the Jira statuses available in Jira Projects

5. For each status in the workflow of your Jira project, select one of the Process Steps (you can set more than one Jira Status to use the same Jira Align Process Step, although we do recommend that your Process Steps match your Jira States making such a configuration unnecessary)

6. When all required statuses have been mapped to steps, scroll to the bottom of the list of Jira Statuses (which is not the bottom of the page) and click Update Steps 

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

1. In Jira Align, go to Settings > Jira Settings > Manage Projects

2. Click the State Mapping link at the end of the row for the desired Project

3. Make sure the toggle under Process steps mappings is enabled
4. Select Feature (or another Jira Align issue type that syncs with Jira Software) from the Work item type dropdown to see the list of configured Jira Align Process Steps
5. Select one of the Jira Statuses within the selected Jira Project for each Jira Align Process Step. (If you have less Jira Statuses then Jira Align Process Steps , then you can configure the same Jira Status against more then one Jira Align Process Step, however when doing this make sure that you match any many-to-one relationships configured in Path 3)
6. Changes are saved automatically, so click Close when all the required mappings have been set.

Path 2 (State Mapping) and Path 4 (Process Step Mapping) are mutually  exclusive, meaning you cannot configure both paths

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

1. Go to Portfolio > choose Portfolio > More Items > Process Flows (Value Streams)

2. Open the details of the Process Flow for the level (Feature, Stories etc) and Program at which the Process Steps have been defined

3. Make sure the Map to State toggle is enabled and change to the Process Steps Tab

4. For each Process Step select an appropriate State (noting that it is possible to use the same state with more then one Process Step, however when doing this make sure that you match any many-to-one relationships configured in Paths 1 & 3)
5. Click Save / Save and Close 

This mapping is bidirectional and immediate, but only applied to updates made in Jira Align. It has no effect if the Jira Align State or Process Step is modified by changes made in Jira that are synchronized by the Jira Connector.

Output and Summary Notes

• For any given Jira project/Board that is being synchronized, make sure the required steps are completed for all your synchronized work item types i.e Features (Jira Epics) and Stories have separate configurations.

• Once configured 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 timings are dependent upon the “Timer on Jira Issues” that have been configured in the Jira Align > Settings > Jira Settings> Jira Setup page.

Related Materials

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

• Jira Software Administration Support Document: “Working with workflows”
• Jira Align KB article: 'How to use Custom Jira Story Types with different workflows when integrated into Jira Align using the Jira Connector"