It's not the same without you

Join the community to find out what other Atlassian users are discussing, debating and creating.

Atlassian Community Hero Image Collage

How to Configure State Mappings between Jira Software and Jira Align

Configure State mapping from Jira Software to Jira Align

To view or configure state mappings from Jira Software to Jira Align, navigate to Jira Align Administration > Jira Settings and click the State Mapping tab.

State mapping can be configured for three work item types in Jira Align:

For each work item type, there is a Jira State ID, a Jira State Description, and a Jira Align State.

State Mapping Details

Explanations of the Jira Align states for each work item type are as follows:

Features (Jira Software Epics)

There are six Jira Align states for features:

0 - Pending Approval

1 - Ready to Start

2 - In Progress

3 - Dev Complete

4 - Test Complete

5 - Accepted

Notes:

  • The synchronization of Jira Align features and Jira Software epics is bi-directional. 
  • If an issue in Jira Software is in a status that is not mapped to a state in Jira Align, the Jira Align state will default to 0 - Pending Approval.
  • Status mapping from Jira Align to Jira will not move a Jira issue out of a Resolved Status.  You would need to update the Status in Jira then sync the update to Jira Align. 

Stories (Jira Software Stories)

There are six Jira Align states for stories , five of which are available for mapping from Jira Software to Jira Align:

0 - Pending Approval

1 - Ready to Start

2 - In Progress

3 - Dev Complete

4 - Test Complete

Notes:

  • The Accepted state for stories is not configured on this panel, as the Accepted status from Jira Software to Jira Align is based off of the Accepted Date field.  The Accepted Date field is configured in the Jira Align Administration > Jira Settings > Jira Setup tab in the Custom Fields section.
  • A combination of Done + Resolution states in Jira Software is required in order to transition a story's state to Accepted in Jira Align.
  • The synchronization of story issue types between Jira Software and Jira Align is bi-directional. 
  • If an issue in Jira Software is in a status that is not mapped to a state in Jira Align, the Jira Align state will default to 0 - Pending Approval.
  • When a connector is first enabled, all statuses that exist in an environment will appear on the Status Mapping page.  You will only need to configure statuses that you plan to use with integrated projects. 
  • If new statuses are added to a Jira Software environment, they will need to be manually added for each work item type on the State Mapping panel in Jira Align or the following steps will need to be run:
    1. Navigate to Jira Align Admin > Jira Settings > Resync Configuration
    2. Click Configuration Data Pull.
    3. The Configuration Data Pull button will return when the Resync is completed
  • Status mapping from Jira Align to Jira will not move a Jira issue out of a Resolved Status.  You would need to update the Status in Jira then sync the update to Jira Align. 

Tasks (Jira Software Sub-Tasks)

There are three Jira Align states for tasks:

1 - Not Started

2 - In Progress

3 - Done

Notes:

  • A Jira Software sub-task will map to a task in Jira Align.
  • If an issue in Jira Software is in a status that is not mapped to a state in Jira Align, the Jira Align state will default to 0 - Pending Approval.
  • A sub-task in Jira Software must be associated with a story.
  • A sub-task's status is a one-directional synchronization from Jira Software to Jira Align, but other items are bi-directional.  For more information, see the Jira Synchronization article.
  • By default, tasks in Jira Software don’t synchronize with work items in Jira Align. However, you can map Jira Software tasks with Jira Align stories by configuring a custom issue type. This includes tasks that aren’t associated with parent stories. To synchronize tasks from Jira Software to Jira Align:
  1. Navigate to Jira Align Administration -> Platform -> Dropdowns , select Story Type, add Task and save the dropdown.Next, navigate to the Jira Align Administration -> Jira Settings -> Custom Issue Types tab. 
  2. Select Add
  3. Type in Issue Type of Task, select Story Type of Task from the drop down menu, and click the Save button.
  4. With these settings in place, the connector synchronizes the issue type of task from Jira Software and treats it like a story.

Defects (Jira Software Bugs)

There are nine Jira Align states for Defects:

Active

In-Work

Pending Test

Verifying

Fixed

Not A Bug

CNR By Design

Postponed

Duplicate

Notes:

  • Jira Software bugs map to Defects in Jira Align.
  • As of Jira Align version 10.58, Defect synchronization is bi-directional between Jira Software and Jira Align.
  • Defect status in Jira Align is a boolean value - either Open or Closed. 
  • If a bug in Jira Software is in any status other than Resolved, the defect's status will be Open in Jira Align.
  • If a bug's Resolution is set to Done in Jira Software, the Defect will be set to Closed in Jira Align.
  • Known Issues: 

Map Canceled and Deleted states from Jira Software to Jira Align

Canceled States

The Canceled state is configured from Jira Align Administration > Jira Settings > State Mapping under Jira Canceled State ID:

  • The Cancelled state ID is defined in Jira Software - it is different per Jira instance.
  • An API call can be run from the Jira UI to get the ID codes for each status.
  • If an work item is canceled in Jira Software, it will be sent to the Canceled Objects bin in Jira Align.
  • To revert a canceled work item, it must be done from Jira Software by changing the state of the work item.  For example, by changing the state of a storyto In Progress, Jira Align restores the story to the backlog and sets the state to In Progress
  • If an item is canceled in Jira Software, and then manually restored to the backlog in Jira Align, the item will be moved back to the Canceled Objects bin by the connector as Jira Align is unable to undo a resolution in Jira Software. 

Deleted States

  • Moving an issue to a Deleted (or equivalent) status in Jira Software will lead to a hard delete in Jira Align when a mapping is configured.  This means that if the status in Jira Software is changed from Deleted to another status, the corresponding Jira Align work item will be restored as a completely new  work item with none of the original Jira Align audit log entries.
  • To configure the deleted item state mapping:
    1. In Jira Software, add a status to the workflow called Delete.
    2. Use the Jira API to obtain the ID for the Deleted status. The API uses the URL format: https://mycompany.atlassian.net/rest/api/latest/issue/CON-79/transitions?expand=transitions.fields
    3. Navigate to Jira Align Administration > Jira Settings > Jira Setup.
    4. In the Delete Item Status box in the Custom Fields section, enter the Jira Software Deleted status ID.

Configure state mapping from Jira Align to Jira Software

To configure state mapping from Jira Align to Jira Software:

  1. Navigate to Jira Align Administration -> Jira Settings.
  2. On the Manage Projects tab, a State Mapping link exists for each project.  To configure mappings, click the State Mapping link.

Notes:

  • State mapping will need to be configured from Jira Align to Jira Software for the story and feature work items.State mappings for Jira Align tasks don't need to be configured, since their states only synchronize one-way from Jira Software to Jira Align. 
  •  All numbered states will need to be configured from Jira Align to Jira Software for each integrated project.  
  • There is an optional Canceled state mapping that will update Jira Software issues to a selected Canceled status when moving Jira Align items to the Canceled Items bin.  
  • The Update all Jira Projects button will update all projects with the same state mapping from Jira Align to Jira Software.  Please use caution before using this functionality!
  • Selecting the Preload and Update button will suggest potential state mappings.  Please review that the populated statuses line up to your integrated Jira project before saving the mapping.
    • Note that clicking the button not only loads the suggestions, it also updates all the fields. In other words, if you click Preload and Update after having something configured previously, the fields will be overwritten.

3 comments

Mark Cruth Atlassian Team Jan 06, 2020

If you come across issues with state mapping for stories, also check out this article from Kent:

https://community.atlassian.com/t5/Jira-Align-articles/A-Jira-Align-Story-synced-from-Jira-is-Marked-Accepted-but/ba-p/1225126

Like Tim Keyes likes this
Rae Gibbs Atlassian Team Jan 24, 2020

@Kent Baxley Regarding the mapping of the Deleted state, if this is mapped and an issue is deleted, with that automatically be picked up in the sync and deleted in JA?  Or, do you need to run the Deleted Issues report in Jira Management?

Like Kent Baxley likes this
Kent Baxley Atlassian Team Jan 24, 2020

@Rae Gibbs - I tested this just now:

* Mapping for Delete was configured on Jira Align

* Logged into Jira and set an issue to "Deleted"

* The corresponding Jira Align story was hard deleted once the sync occurred(i.e. it was deleted completely from the app).

* I then ran the Deleted issue report to see if the corresponding Jira item showed up in there.  It did not. 

So, when marking an issue deleted in Jira, the JA work item is removed and there's no additional cleanup required (i.e. no need to check the deleted issue report).  

Hope that helps!

Like # people like this

Comment

Log in or Sign up to comment
TAGS
Community showcase
Published in Jira Align

Virtual/Remote PI Planning Best Practices and FAQ Table of Contents

Due to recent challenges of most companies having to move to virtual and remote PI planning events, the Jira Align Solutions Architects wanted to start to capture some best practices and FAQ Table of...

3,547 views 3 31
Read article

Community Events

Connect with like-minded Atlassian users at free events near you!

Find an event

Connect with like-minded Atlassian users at free events near you!

Unfortunately there are no Community Events near you at the moment.

Host an event

You're one step closer to meeting fellow Atlassian users at your local event. Learn more about Community Events

Events near you