How to use Custom Jira Story Types with different workflows when integrated into Jira Align using the Jira Connector
Summary
In Jira, it is possible to create custom issue types that are handled in Jira Align as ‘story’ types. Business processes may make it necessary to use different workflows and statuses, between the different issue types in Jira. Using multiple Jira workflows with different statuses between the different ‘story’ types within a single Jira project introduces some complexities and limitations in the Jira Align mapping configurations that do not exist if the custom issue types use the same workflow and statuses as those applied to Stories.
Due to this the recommended practice is: Within a single Jira project, use the same workflow for both the default and custom story types.
This article discusses the configuration steps and limitations of using different workflows
Environment
Jira Align
Solution
Jira Configuration
Take note of the Project Name and Key (of the integrated project)
Take note of the Board ID (within the integrated project)
Review and take note of the IDs for the Epic, Story & Sub-task issue types (as used in your Jira Project)
- check in Settings > Issues > Issue typesReview and take note of the Statuses and Status IDs used in the Workflow for the Story issue type
- check in Settings > Issues > Workflows and Settings > Issues > StatusesEither identify an existing but different workflow or configure a new set of statuses and a new workflow that will be used by the new custom issue type
- use Settings > Issues > Workflows and Settings > Issues > StatusesTake note of the names and IDs of the statuses used in this workflow
- check in Settings > Issues > StatusesCreate the new custom issue type (as a standard issue type), make sure it is related to the scheme for your project and has the correct workflow assigned.
- use Settings > Issues > Issue types and Settings > Issues > Workflow SchemesTake note of the ID for this new custom issue type
- check in Settings > Issues > Issue types
Jira Align Configuration
When reading this section, references to Jira Step n, mean steps in the above section, references to Step X:n, mean steps in the Jira Align sections.
In Jira Align, some of the configuration pages refer to Jira Statuses as Jira States
For ease of reading this has been split into separate expandable sections covering different areas of Jira Align.
For New Navigation: Open Solution Room > More Items > Process Flows (Value Steams) - For Old Navigation open Solution > Manage > Process Flows (Value Steams)
Click +Add Process Flow
In the Level field, choose Story
Chose the correct Program
Fill in a Name and Team Description
Enabling the Map to State toggle is optional, but does change the behaviour (see the Usage Recommendations and Limitations section below)
Click Save
Select the Process Steps tab
Add one process step for each story level status identified in Jira Step 4 and Jira Step 6 (in effect covering all of the statuses for all of the story types in the same project).
It is strongly recommended to have a naming convention for the Process Steps that clearly identifies which Process Step is associated with which story type.
If Map to State is enabled, then this will result in some states being connected to more then one process step
Adjust the order of Process Steps as required (in the example image shown below, any Process Steps with CR in the name, were Process Steps to be mapped to Jira statuses for a custom issue type called Change Requests, those without CR were for standard stories)
Click Save and Close
Go to Settings/Administration > Details Panel Settings
Chose the correct Portfolio and a Work Item of Story
Enable the Process Step toggle in the Active column and click Save
Open Settings/Administration > Jira Setup > State Mapping (tab)
Set the Type dropdown to Story
Make sure that all of the Statuses noted in Jira Step 4 and Jira Step 6 are mapped to a valid state
Go to Administration > Jira Settings > Manage Projects > Manage Custom Fields
Under Sync Process Steps with Jira States change the Level to Stories
Set the Process Flows field to that named in Step B:5
For each of the Jira Statuses noted in Jira Step 4 and Jira Step 6 configure a connection to the correct Process Step. The following image shows the Jira Statuses used with the example of setting up a custom issue type for Change Requests. In addition to those entries shown in this image, the Jira Statuses for the standard story type were also configured but not shown as in our test environment there are hundreds of Jira Statuses in this list and you only need to configure those used in the same Jira project
Click Update Steps and then close the pop-up page
In Settings/Administration > Jira Settings > Manage Projects locate the Jira Project from Step C:2 and click the State Mapping link for that project
Make sure the Process steps mappings toggle is enabled and Work item type is set to Story (or if using an old version of Jira Align that the State / Process Step (green box) is set to Process Step with the Work Item type of Story)
Configure each Process Step to connect to the correct Jira State (Status) based on the details noted in Jira Step 4 and Jira Step 6. The below images continues with the example of configuring a custom issue type for Change Requests
Click Preload and update (or Update)and then close the pop-up page
As a recommendation, also ensure that a standard Process Step configuration is implemented for the mappings of Jira Epics to Jira Align Features
Usage Recommendations and Limitations
If the Jira story and custom issue types use different workflows and statuses from each other, then Process steps MUST be used in Jira Align. If configured for just State Mappings, then updates to Jira Align States (without using a Process Flow) will not be possible for both issue types as a Jira Align State for a story type cannot be mapped to more than one Jira Status
As the State field in the details of a Story cannot be hidden from a Jira Align user, team members will need to be trained to only make changes to the operational state of a story by adjusting the Process Step (they should never change the State)
When choosing a Process Step, team members need to be aware of which issue type they are adjusting and only choose process steps for that issue type - this is why it was recommended to use a clear naming convention for the Process Steps in Jira Align step B:10
If a Jira Align user accidentally chooses a Process Step that is linked to a different issue type, then the change will not sync to Jira and the audit log will show a Jira Align State to Jira Status Error
Jira Align State to Jira Status Error: For the Jira issue’s current status (nnnnn), a Jira transition to map from an Jira Align State (nnn) to Jira Status (nnnnn) could not be found. Please check the Jira Align State to Jira Status mappings.
The following table shows how the Map to State setting (Jira Align step B:6) changes the behaviour
User Action | Map to State | Related State/Process Step Changed | Issue Status Synchronized to Jira | Audit Log Error |
|---|---|---|---|---|
State of Story or Custom Story changed in Jira Align | Disabled |
|
| No Error |
State of Story or Custom Story changed in Jira Align | Enabled |
|
| No error if the Process Step is valid for the issue type. If invalid, then the Jira Align State to Jira Status Error will be recorded. |
Process Step of Story or Custom Story changed to a valid choice for the issue type in Jira Align | Disabled |
|
| No Error |
Process Step of Story or Custom Story changed to a valid choice for the issue type in Jira Align | Enabled |
|
| No error |
Process Step of Story or Custom Story accidentally changed to an invalid choice for the issue type in Jira Align | Disabled |
|
| Jira Align State to Jira Status Error |
Process Step of Story or Custom Story accidentally changed to an invalid choice for the issue type in Jira Align | Enabled |
|
| Jira Align State to Jira Status Error |
Process Step NOT changed
Process Step changed to the 1st Process Step (for the chosen State) from the order configured in Jira Align step B:12 (this may be an invalid Process Step for the issue type)
Jira Align State not immediately changed, but after the Jira Status is changed, the next connector sync will change the Jira Align State