Mastering the art of creating custom Jira workflows unlocks the power to manage any process in Jira. An earlier post discussed Jira issue statuses - the building blocks of a Jira workflow. This post will discuss Jira workflow transitions – the connecting tissue between those statuses.
What is a Jira Workflow Transition ?
Jira workflow transitions are the mechanisms through which a Jira issue progresses from one status to another. Workflow transitions come in three varieties:
- Global transitions allow issues to be transitioned from any status to the target status. Workflows that use global transitions are called simplified workflows, and allow for maximum flexibility.
- Common transitions connect two different Jira workflow statuses. Use common transitions when you want to enforce a specific order of operations in your Jira workflow.
- Although rare, Self-reflecting (looping) transitions can be used to trigger automation and/or post-functions, or to capture information on a transition screen without changing the issue status. Self-reflecting transitions are executed from the Actions menu, rather than from the Transitions dropdown.
Adding, Editing or Deleting Jira Workflow Transitions
Adding, editing and deleting transitions all happens in the workflow editor (Settings > Workflows, then click on the pencil icon to open edit mode). Sometimes Jira will let you edit a workflow directly. At other times you will need to make a copy of the workflow, make your edits in the copy, and then replace the old workflow with the new one in your workflow scheme. The workflow editor allows you to use either a text or a diagram interface.
Adding Transitions
- To add a new transition, click the Add transition button. Select the From and To statuses and give the transition a name. You can also add a screen (see below) when creating a new transition.
- If you want to create a global transition (meaning issues from any status in the workflow can be transitioned to the target status), select the target status and tick the Allow all statuses to transition to this one checkbox.
Editing Transitions
- Selecting a transition and clicking on the Edit button will allow you to edit the transition name, description, and screen.
- In the diagram view of the editor, when you select a transition, you will see black dots that anchor the transition arrow to the status. You can grab the transition arrow at one of these points and drag it to another status to edit the transition.
Deleting Transitions
- To delete a transitions, select the transition and click on the Delete transition link.
- Note that Jira will highlight any statuses that don’t have a transition in red.
Jira Workflow Transition Naming Conventions
Since transitions are the engine that propel an issue through a workflow, transition names should clearly tell the user what to do (think verbs), without any ambiguity. As with status names, it’s recommended that transition names not be too specific, to ensure that the workflow can be used by multiple projects. Good transition names include:
- Approve
- Reject
- Start work
- Respond to customer
- Respond to support
- Send to QA
Jira Workflow Transition Screens
Jira gives you the option to add a dedicated screen to any transition. Unlike other screens, transitions screens are not visible when you create or view the issue. They are used to collect data specific to the transitions (data that was likely not available when the issue was created), and only appear during the transition. However, the information collected on a transition screen is available to queries and search results.
The most common use of transition screens is to set a Resolution when an issue is closed. Transition screens are also useful in any workflow that includes an option to approve or reject what has been done on an issue. If the approver rejects the work and either cancels the issue, or sends it back to a previous status, you’ll want to know why. That’s information you can capture on a transition screen.
Creating a Jira Workflow Transition Screen
Transition screens work differently than other screens in Jira and are not part of the project's screen scheme. To add a screen to a transition:
- Navigate to Jira settings > Issues > Screens and click Add screen.
- Name and description and save the screen.
- Open the new screen and add the desired fields.
- In the workflow, click on the transitions where you want to add the screen.
- Click the Edit button.
- Select the indicated screen from the dropdown.
Jira Workflow Transition Options
When you click on a transition in the workflow editor you’ll also see a list of Options. These are powerful tools that allow you to build increased control and increased efficiency into your workflows.
Workflow Properties
Workflow properties allow you to add an extra level of control over what can be done, and by whom, at specific points in your workflow. Workflow properties include:
- jira.issue.editable – This property can be set to true or false to allow the issue to be editable when it’s in a particular status
- jira.permission – Permission properties can be used to restrict (beyond what is controlled by the permission scheme) which users can execute which actions. See the Atlassian documentation for examples.
- jira.field.resolution – The resolution property can be set to include or exclude, allowing you to control which Resolutions are available on a given transition.
Workflow Triggers
Triggers allow you to automatically transition a Jira issue in response to an event in a development tool. Triggers can be configured to respond to events in Bitbucket, GitHub, GitHub Server, Crucible and Fisheye. Using triggers is a good way to keep Jira software projects in sync with the development environment.
Workflow Conditions
Conditions allow you to control by whom, and under what circumstances, an issue can be transitioned. If the condition is not met, then the user will not be shown the transition option. In some cases, this will mean that a given user will not have the option to transition the issue at all. Example workflow conditions include:
- User conditions (Only the reporter, assignee, member of a given group, etc.)
- Previous status condition to check whether the issue has transitioned through a specified status
- Value field only allows the transition if a field value is equal to a given value
Workflow Validators
Validators check for a certain condition before allowing the transition. If the validator is not met, then the transition will fail. Validators are a powerful tool for enforcing your processes. Example workflow validators include:
- Date window or date compare
- Field value (that a field has a value, or that the value has been updated)
- Built-in app validators (All checklist items complete, Clockwork time logged)
Workflow Post Functions
A post function is an action that happens after successful execution of the transition. Post functions are a useful way to keep momentum by automatically completing the next step(s). Post functions can include:
- Assign the issue (Current User, Lead Developer, Reporter)
- Update a field value
- Built-in app post functions (Complete all Checklist items)
Using Jira Workflow Transitions with Automation
As you can see, workflow transition options are powerful tools that can save users a lot of time. A well-configured workflow is almost self-propelling.
There is one other feature you should consider integrating with your workflows – Jira automation. Automation rules consist of:
- A trigger which tells the rule when to run
- Conditions (optional) which limit which issues will be impacted by the rule
- The actions that the rule will take
Workflow transitions can be used as both triggers (When issue transitions from STATUS A to STATUS B…), add actions - as seen below.
.png)
A well-designed workflow that makes use of workflow transition options and integrates with Jira automation greatly improves teams' efficiency. Time-saving however, is not the only benefit. Workflow tools allow you to standardize processes across multiple teams and projects. They empower you to build compliance and best practices directly into Jira, supporting your teams in doing their best work.
