How to Configure State Mappings between Jira Software and Jira Align

[#1]

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:

• Features (Jira Software Epics)
• Stories (Jira Software Stories)
• Tasks (Jira Software Sub-Tasks)
• Defects (Jira Software Bugs)

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 status in Jira (naming convention subjective to the organization) with the category being "Done" + Resolution results in a resolution date being set, which will trigger the Jira Align state to be set to "Accepted". 
• 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.
  • Even though a story moving to Accepted in Jira Align is controlled by Done + Resolution, Done should be mapped to 4 - Test Complete.
• 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: 
  • Please feel free to add yourself as a watcher to the issue below for tracking:
    • JIRAALIGN-915 Bi directional Defect Sync - Tag and Label sync is inconsistent

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.

[Mark Cruth]

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

[Rae Gibbs]

@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?

[Kent Baxley]

@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!

[Carlos Sanchez]

Hello @Kent Baxley, you say that
       "The synchronization of Jira Align [...] and Jira Software [...] is bi-directional." 

But my understanding is that the JA > JS mapping must be set explicitly as well, or will in fact not happen, and indeed you say that
       "State mapping will need to be configured from Jira Align to Jira Software".

Can you please clarify?

Also, "the Update all Jira Projects button" is dangerous and should be optional: See ticket https://getsupport.atlassian.com/servicedesk/customer/portal/51/ALIGNSP-9000?error=login_required&error_description=Login+required&state=aec19d55-9d32-4457-82a5-cc8f7a804c91

[Rae Gibbs]

Hey Carlos - Kent is no longer with Atlassian and thought I would respond to your question.  Since the mapping of states/statuses is bi-directional between Jira and Jira Align, this mapping needs to be configured both ways.  You must select what Jira statuses map to which Jira Align states and then the reverse of which Jira Align states (or process steps) map to which Jira statuses.  This is so that no matter which tool it is updated in, it will properly map to the other tool when it runs its sync.

When there are companies that do not use standardized workflow across projects, you are correct that the Update all Jira Projects button can be dangerous.  Using the State Mapping links by project on the Manage Projects tabs accommodates the scenario of using different workflows by project.  If this is the case and the Update all Jira Projects button is clicked, it will override what has been set for the other projects and they will need to be set up again.  

One could have the opinion that having different workflows across projects is an administrative nightmare and not conducive to scaling.  Having a standardized workflow would be a more optimal scaling option but in reality, companies cannot always achieve this for various reasons.

[Sathish Ponnusamy]

@Rae Gibbs @Mark Cruth @Kent Baxley 
Hi There, What about tasks in jira? Some projects use tasks [not sub tasks] in jira.
How to map them in Jira Align.

[Carlos Sanchez]

@Sathish Ponnusamy I believe that JS Tasks map to JA Stories (of type Task).

[Rae Gibbs]

@Sathish Ponnusamy You can map them as stories via Custom Issue Type. Here's an article you can reference on how to do that.

[Federica Marchetti]

@Kent Baxley link Jira Synchronization article is broken, any chance to find it?