Create complex workflows in Jira
10 min
By the end of this lesson, you’ll be able to:
- Use triggers to automatically transition work
- Use workflow rules to control transitions by restricting when they occur, validating criteria during transitions, and performing actions after transitions execute
- Use properties to add detailed behavior to workflows
Use triggers to automatically transition work
Triggers automatically transition work when certain events occur in your development tools, like Bitbucket.
👉 For example: When a user creates a pull request, update the status of the corresponding Jira work item.
Triggers support developers while they complete Jira work. They can remain focused while providing insight to stakeholders in reports and work activity.
To use triggers, a Jira admin needs to integrate your site with a development tool. Then, you’ll have events related to your development tool that you can use in workflows.
When a transition triggers automatically, it ignores any transition rules, or permissions configured on the transition. However, they still apply when a user manually transitions the work item.
To add a trigger to a workflow:
- In the new workflow editor, click a transition. These are arrows going from one status to another with a label indicating the name of the transition.
- In the side panel, under Triggers, add a development trigger, like Branch Created. The workflow will now execute this transition when the Branch Created event occurs.
It’s usually not a good idea to configure triggers for global transitions. Triggers may accidentally transition work from Done to In Progress, for example, since any status can transition to any other status.
Use workflow rules to determine whether a transition occurs
Restrict transition rules, previously known as conditions, specify criteria that the workflow must meet before it can transition a work item. Workflow rules control who performs a transition and under what circumstances.
👉 For example:
- The user must be a QA team member to close work.
- The user must be the current assignee to start progressing on the work item.
- The payment terms must have been defined to send out an invoice.
Restrict transition rules are prerequisites for the transition. If the user or work item doesn't meet the conditions in the rule, the user won't be able to transition that work item.
👉 For example: If a user doesn't meet a Restrict transition workflow rule for the Done transition, then that user can't:
- Select Done in the Status field on the work item.
- Drag the work item to the Done column on the board.
- Include the work item in a bulk transition of multiple work items to Done.
- Transition the work item to Done through the More actions menu on a dashboard gadget.
You can add multiple restrict transition workflow rules to a transition using ‘and' or 'or’ restrict transitions.
👉 For example: To transition a work item from In Progress to Done, a user must be the Assignee for the work item and in either the Developer role or the Administrator role.
To add a restrict transition rule to a workflow:
- In the new workflow editor, click a transition.
- In the side panel, under Rules, click Add rule (represented by +).
- Under Rule types, select Restrict transition.
- Select the rules you need and configure them.
Depending on your requirements, you can add a restrict transition workflow rule restricting who can transition a work item or restricting what statuses the work item should have.
Use workflow rules to check criteria during a transition
Validate details transition rule, previously known as Validators, check that any input given during the transition is valid before it transitions the work item.
👉 For example:
- When a user reopens a support ticket, they have to add a comment.
- When a user closes a payment request, they must have the Administer space permission.
- When a user fixes a bug, they must enter a fix version.
You can use these workflow rules to show an error when users don’t meet the criteria. If a transition's workflow rule fails, the workflow won’t transition the work item or execute the perform actions workflow rules (previously known as post functions).
In company-managed spaces, these workflow rules work with transition screens to ensure users enter correct data in fields. Jira admins must make the fields required on those transition screens. Team-managed spaces don’t have this capability.
To add a validate details transition rule to a workflow:
- In the new workflow editor, click a transition.
- In the side panel, under Rules, click Add rule (represented by +).
- Under Rule types, select Validate details.
- Select the workflow rule you need and configure it.
Use workflow rules to act after a transition executes
Perform actions workflow rules, previously known as post functions, perform actions after a transition executes.
👉 For example:
- Automatically assign bugs to a QA engineer.
- Enter the current date in the Shipped Date field.
- Copy the value from the parent work item in the Priority field.
Before a perform actions workflow rule can execute, the workflow must meet all restrict transition and validate details transition rules for that transition. Depending on the statuses and transitions in your workflow, you may see some default perform actions workflow rules.
One of the most common use cases for perform actions transition rules is to manage the Resolution field.
👉 For example: You can use a perform actions transition rule to clear the Resolution field whenever a work item transitions from the Done status to the In Progress or To Do statuses. You can also use a perform actions transition rule to automatically set the Resolution field to Done when a work item transitions to the Done status.
To add a perform actions transition rule to a workflow:
- In the new workflow editor, click a transition.
- In the side panel, under Rules, click Add rule (represented by +).
- Under Rule types, select Perform actions.
- Select the workflow rule you need and configure it.
Use properties to add detailed behaviors to your workflows
You can use properties to configure more detailed behaviors for your workflows.
👉 For example:
- You can restrict who can do what in a certain status.
- You can restrict the resolutions available in a transition.
- You can reorder the transition buttons within work items.
- You can add translate buttons if you have an international team.
Workflows commonly use properties to further restrict permissions beyond a company-managed space’s permission scheme.
👉 For example: The permission scheme only enables Jira admins and space admins to delete work items. You can use a property to only enable Jira admins to delete work with a Done status.
It’s best to manage permissions exclusively in your permission scheme. However, you may have specific use cases worth the administrative burden.
Every property has a key and a value. The key indicates what the property is, while the value specifies necessary data.
👉 For example: You don’t want users to edit work with the Done status. On the Done status, you add a property with the key ‘jira.work.item.editable’ and the value ‘false.’ The key indicates that the property will control if the work item is editable. The value specifies that it is not editable.
To add a property to a workflow:
- In the new workflow editor, click a status or transition.
- In the side panel, at the bottom next to the Properties heading, click Add property (represented by +).
- Click Add new property.
- Enter a key and a value, then click Save.
For more property keys and values, see Atlassian Documentation.
Let’s explore an example
Kiri, a Jira admin, is working with developer teams to configure a workflow for the Feature work type. She has a set of requirements:
- To move a Feature to In Progress, the current user must have the Developer role.
- When a Feature moves from To Do to In Progress, copy the Assignee field to the Developer field.
- When a Feature moves from In Progress to Done, the Time Spent field must have a value.
👇 Watch this video to learn how to configure a workflow for these requirements.