Advanced workflow configuration
This page describes configuring transitions in Jira workflows. For information about the basics of workflows – see Working with workflow.
As a Jira administrator, you can control the following aspects of a transition's behavior:
- Triggers – transition Jira issues when certain events occur in a connected development tool, such as Atlassian's Bitbucket or Stash.
- Conditions – check that a transition should be performed by the user.
- Validators – check that any input to the transition (for example, by a user) is valid, before the transition is performed.
- Post functions – carry out additional processing, after a transition is performed.
- Properties – are key-value pairs that can be used to further customize transitions.
Also on this page:
Triggers
Jira administrators can configure triggers in Jira workflows that respond to events in your linked development tools. This allows you to set up your development tools and Jira workflows so that, for example, when a developer creates a branch to start work on an issue in Atlassian's Bitbucket or Stash, the issue will automatically be transitioned from 'Open' to 'In progress'.
If you haven't set up a trigger before or you want to learn about triggers in more detail, see our guide on triggers here: Configuring workflow triggers. The guide also shows you how to configure a workflow with triggers, similar to this sample development workflow: Development Workflow with Triggers (from Atlassian Marketplace).
Configure triggers
To see, or to set, triggers for a transition, edit the workflow that contains the transition, select the transition, then click Triggers in the properties panel for the transition.
To add a trigger to a transition:
- Log in as a user with the 'Jira Administrators' global permission.
- Choose Administration (
) > Issues. Select Workflows to open the Workflows page, which displays all of the workflows in your system. - Click Edit for the workflow that has the transition you wish to change.
In the Workflow Designer, select the transition.
- Click Triggers in the properties panel to show the triggers configured for the transition.
- Click Add trigger on the Triggers tab to configure a trigger.
Conditions
Conditions control whether a transition should be executed by the user. As examples, conditions can be used to:
- allow only the reporter to execute a transition.
- allow only users with a certain permission to execute a transition.
- allow execution only if code has, or has not, been committed against this issue.
If a condition fails, the user will not see the transition button on the 'View issue' page, and so will not be able to execute the transition.
Conditions cannot validate input parameters gathered from the user on the transition's screen – you need a validator to do this.
The following sections describe:
Adding a condition
To add a condition to a transition, edit the workflow that contains the transition, select the transition, then click Conditions in the properties panel for the transition.
To add a condition to a transition:
- Log in as a user with the 'Jira Administrators' global permission.
- Choose Administration () > Issues. Select Workflows to open the Workflows page, which displays all of the workflows in your system.
- Click Edit for the workflow that has the transition you wish to change.
In the Workflow Designer, select the transition:
- Click Conditions in the properties panel.
On the Conditions tab, you can see any conditions that have already been set.
When you click Add condition, you can choose from the available conditions, and set any necessary parameters for the condition. Additional conditions may be available from installed apps. or you can create your own conditions using the app system; see the Workflow app Modules for details.
Note that you can also edit the transition in 'text' mode.
Grouping conditions
You can construct complex conditions by grouping and nesting conditions. Change any condition into a group by clicking the 'Add grouped condition' icon for the condition. Now you can add further conditions to this new group, as described above.
You can toggle the logic for how the conditions in a group are applied between All and Any.
Validators
Validators check that any input made to the transition is valid before the transition is performed. Input can include that gathered from the user on the transition's screen.
If a validator fails, the issue does not progress to the destination status of the transition, and the transition's post functions are not executed.
Adding a validator
To add a validator to a transition, edit the workflow that contains the transition, select the transition, then click Validators in the properties panel for the transition.
To add a validator to a transition:
- Log in as a user with the 'Jira Administrators' global permission.
- Choose Administration () > Issues. Select Workflows to open the Workflows page, which displays all of the workflows in your system.
- Click Edit for the workflow that has the transition you wish to change.
In the Workflow Designer, select the transition:
- Click Validators in the properties panel.
On the Validators tab, you can see any validators that have already been set.
When you cllck Add validator you can choose from the available validators and set any necessary parameters for the validator.
Note that you can also edit the transition in 'text' mode.
Post functions
Post functions carry out any additional processing required after a transition is executed, such as:
- updating an issue's fields
- generating change history for an issue
- adding a comment to an issue
- generating an event to trigger email notifications
The following sections describe:
Essential post functions
Every Jira transition has the following essential post functions, which are performed in this order:
- Set issue status to the linked status of the destination workflow status.
- Add a comment to an issue if one is entered during a transition.
- Update change history for an issue and store the issue in the database.
- Reindex an issue to keep indices in sync with the database.
- Fire an event that can be processed by the listeners.
These essential post functions cannot be deleted from a transition or reordered. However, you can insert other (optional) post functions between them.
Optional post functions
Jira includes several optional post functions that can be added to transitions.
Optional post function | Description |
|---|---|
Assign to Current User | Assigns the issue to the user who is executing the transition. |
Assign to Lead Developer | Assigns the issue to the component lead, if one exists, or project lead. |
Assign to Reporter | Assigns the issue to the user who created the issue. |
Create Perforce Job Function | Creates a Perforce Job (if required) after completing the workflow transition. |
| Notify HipChat | Sends a notification to one or more HipChat rooms. See Using a post function to send HipChat notifications for more information. |
| Trigger a Webhook | Triggers the specified webhook after completing the workflow transition. When you add this post function, you will be asked to specify a webhook. This webhook must already be defined in Jira (see Managing webhooks). |
Update Issue Field | Updates one of the issue's fields to a given value. Fields that can be updated include:
|
Additional post functions may be available from installed apps. or you can create your own post functions using the app system; see the Workflow app Modules for details.
Adding a post function
To add a post function to a transition, edit the workflow that contains the transition, select the transition, then click Post functions in the properties panel for the transition.
To add a post function to a transition:
- Log in as a user with the 'Jira Administrators' global permission.
- Choose Administration () > Issues. Select Workflows to open the Workflows page, which displays all of the workflows in your system.
- Click Edit for the workflow that has the transition you wish to change.
In the Workflow Designer, select the transition:
- Click Post functions in the properties panel.
On the Post functions tab, you can see any post functions that have already been set. When you click Add post function you can choose from the available post functions, and set any necessary parameters. Options for editing or deleting a post function, and for changing the execution order, are at the right of the tab (hover there to see them).
Note that you can also edit the transition in 'text' mode.
Using post functions with the initial transition
You can add post functions to a workflow's initial transition when you need to perform processing tasks – such as setting a particular field's value – when an issue is created. The initial transition is called 'Create' (if you created a blank workflow) or 'Create Issue' (if you copied the system workflow).
Jira includes the following essential post functions that are specific to a workflow's initial transition and that are performed in this order:
- Create the issue.
- Fire an event that can be processed by the listeners.
The following optional post functions are available specifically for the initial transition:
Optional post function (initial transition only) | Description |
|---|---|
Create Comment | Adds a comment to an issue if one is entered during a transition. |
Update Issue Status | Sets the issue's status to the linked status of the destination workflow status. |
Store Issue | Stores updates to an issue (no change history is created). |
Additionally, the standard optional post functions can also be added to an initial transition,
Optional post functions added to the Create transition must be placed before the 'Create the issue originally' post function.
If you wish, you can configure the initial status for your workflow to go to a different initial transition. See Configuring the initial status for details.
Notes
If you need to set the 'Resolution' field when creating an issue, add the 'Update Issue Field' post function after the 'Create the issue' post function and after that, use the 'Store Issue' post function. The 'Store Issue' post function is useful for setting the Resolution field during issue creation.
However, only use the Store Issue post function where necessary, since it:
- does not generate change history
- is unable to persist fields that have a one-to-many relationship with the issue (for example, 'Version' or 'Component')
Using a post function to set a field
You can use the 'Update Issue Field' post function to set the value of an issue's field after a particular transition is executed.
For example, you might want a transition that moves the issue to a closed status to automatically set the 'Resolution' field.
Example: Using a post function to set the Resolution field:
Edit the workflow that has the transition, and drag from status to another to create a new transition.
- Select either None or a screen that does not contain the Resolution field:
- Add a new post function of type 'Update Issue Field' and:
- Select Resolution from the Issue Field list.
- Select a suitable resolution from the Field Value list.
To create a transition that clears the Resolution field, follow the same steps above for adding an 'Update Issue Field' post function to your transition. However, select None from the Field Value list.
The list of post functions for this transition includes the following statement:
- The Resolution of the issue will be cleared.
Each time one of these transitions is executed, the Resolution of the issue is automatically set or cleared, as specified in these post functions.
Using a post function to send HipChat notifications
You can use a 'Notify HipChat' post function to send a notification to one or more HipChat rooms whenever an issue passes through a transition with this post function. You can also add a JQL query to the 'Notify Hipchat' post function to filter for the issues that will trigger the HipChat notification.
To send HipChat notifications:
- Create or edit your transition.
- Add a new post function of type 'Notify HipChat'.
- On the 'Add Parameters to Function' page:
- Optionally, specify a JQL query. Only issues that match the query will send notifications.
Leave this field empty to send notifications to all issues that pass through this transition. - Select the HipChat rooms you want to link with your workflow transition.
- Optionally, specify a JQL query. Only issues that match the query will send notifications.
Using a post function to send email notifications
Use the 'Fire an event that can be processed by the listeners' post function to fire the 'Generic Event', which is a built-in Jira event that can be used to trigger the sending of email notifications after a particular transition is executed.
Alternatively, you could fire a custom event that you've created specifically for this transition.
When a transition is performed, Jira will:
- Look up the notification scheme associated with the issue's project and identify the users associated with the fired event;
- Send an email notification to each user.
The fired event is also propagated to all registered listeners.
Example: Using a post function to fire the Generic Event to send email notifications:
- Create or edit your transition.
- Click the transition's Post Functions tab and edit the 'Fire an event that can be processed by the listeners' post function.
Select Generic Event from the list of events.
Transition properties
Properties are key-value pairs that can be used to further customize transitions. For example, transition properties can help to extend a copied system workflow to allow language translations.
To view and edit the properties of a transition:
- Select a transition in the diagram.
- Click Properties in the Properties panel.
- Either:
- Add a new property to the transition.
- Delete a property, by clicking the icon to the right of the property.
Important
It is not possible to edit a transition's properties on this page. To change any property's key or value (or both), you must first delete the property you wish to change and add the new updated property.
Note that you can also edit the transition in 'text' mode.
It is possible to implement restrictions on transitions using transition properties. For more information, see Workflow properties.
Customize how transitions appear
When viewing an issue, most of the operations and workflow transitions are available from a row of buttons at the top of the issue.
To change the number of transition buttons from the default of two:
By default, the first two transitions appear as separate buttons in the set of transition buttons. Additional transitions appear in the Workflow menu. The order in which these buttons appear is based on the order defined in the system workflow.
- Shutdown Jira.
- Edit the
jira-config.propertiesfile in your Jira application home directory. See Making changes to thejira-config.propertiesfile for more information. - Change the value of '
X' in theops.bar.group.size.opsbar-transitions = Xproperty of this file to be the number of transition buttons required before the Workflow menu. If this property does not exist in your jira-config.propertiesfile, add it. Otherwise, a default value of 2 is assumed. - Save the updated
jira-config.propertiesfile. - Restart Jira.
To change the order of transition buttons:
To change the order of transition buttons, including additional transitions in the Workflow menu, add the property key opsbar-sequence to each workflow transition that you wish to reorder. Each opsbar-sequence property key requires a property value that defines the order of the transition action on issue views.
- Go to the transition's properties, as described in Transition properties above.
- Type
opsbar-sequenceinto the Property Key field, under 'Add New Property'. - Type a value In the Property Value field, The value must be a positive integer (starting at '0'); it defines the order of the transition buttons on issue views.
Consider using a sequence ofopsbar-sequenceproperty values like 10, 20, 30... to allow new transitions to be easily added later. - Click Add.
Adding the opsbar-sequence property to a workflow transition does not change the order of these transitions in the workflow in Text edit mode. The addition of this property only affects the order of transitions on the View issue page.
Global transitions
Global transitions allow any status in a workflow to transition to a particular status.
You can add a global transition:
- When creating a new status (adding an existing status) – check the Add global transition to status option.
- By selecting a status and checking Allow all statuses to transition to this one in the properties panel for the status.
To create two global transitions that point to the same destination step:
- From the workflow designer, create the first global transition as normal by selecting a step and checking "Allow all statuses to transition to this one"
- Create the second global transition on any other step that does not currently have a global transition pointing to it
- Then from text editor, select the second global transition that you created
- Click on the 'Edit' button and change the 'Destination Step' to the same step that you selected for your first global transition, and then click 'Update'