Configure advanced work item workflows

As a Jira administrator, you can control the following aspects of a workflow transition.

• Triggers – transition Jira work items when certain events occur in a connected development tool, such as Bitbucket.

• 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.

• How transitions appear

• Global transitions

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 a work item in Bitbucket, the work item will automatically be transitioned from 'Open' to 'In progress'.

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:

1. Select > Work items.

2. Click Workflows and then Edit for the relevant workflow.

3. In diagram mode, select the transition arrow. In text mode, select the transition's name from the Transitions (id) column.

4. In diagram mode, click Triggers in the properties panel to show the triggers configured for the transition. In text mode, select the Triggers tab.

5. Click Add trigger on the Triggers tab to configure a trigger.

For more information, check out Configuring workflow triggers.

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 work item.

If a condition fails, the user will not see the transition button on the 'View work item' 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.

Optional conditions

Jira includes several optional conditions that can be added to transitions.

Add 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:

1. Select > Work items.

2. Select Workflows.

3. Select More () and then Edit next to the relevant workflow.

4. In diagram mode, select the transition arrow. In text mode, select the transition's name from the Transitions (id) column.

5. In diagram mode, click Conditions in the properties panel to show the triggers configured for the transition. In text mode, select the Conditions tab.

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 plugins, or you can create your own conditions using the plugin system; see the Workflow Plugin Modules for details.

Group 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 work item does not progress to the destination status of the transition, and the transition's post functions are not executed. 

Add 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:

1. Select > Work items.

2. Click Workflows and then Edit for the relevant workflow.

3. In diagram mode, select the transition arrow. In text mode, select the transition's name from the Transitions (id) column.

4. In diagram mode, click Validators in the properties panel to show the triggers configured for the transition. In text mode, select the Validators tab.

When you click Add validator, you can choose from the available validators and set any necessary parameters for the validator.

Post functions

Post functions carry out any additional processing required after a transition is executed, such as:

• updating fields in a work item

• generating change history for a work item

• adding a comment to a work item

• generating an event to trigger email notifications

Essential post functions

Every Jira transition has the following essential post functions, which are performed in this order:

1. Set the status of a work item to the linked status of the destination workflow status.

2. Add a comment to a work item if one is entered during a transition.

3. Update change history for a work item and store the work item in the database.

4. Re-index a work item to keep indexes in sync with the database.

5. Fire a Generic event that can be processed by the listeners. 

    Do not edit or remove this post function. Changing this essential post function will cause unintended behavior for automations and Marketplace add-ons. If you wish to customize the post function events that fire on a transition, consider adding a custom post function and leave the default event alone.

These essential post functions cannot be deleted from a transition or reordered. However, you can insert other post functions between them.

Post functions that fire events may act differently than you expect. Jira waits to call any notification listeners until the end of the post function sequence. So, your events will fire in the order you expect, but notifications won’t be triggered until the end of the transition.

Optional post functions

Jira includes several optional post functions that can be added to transitions.

Additional post functions may be available from installed plugins, or you can create your own post functions using the plugin system – see the Workflow Plugin Modules for details.

Add 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:

1. Select > Work items.

2. Click Workflows and then Edit for the relevant workflow.

3. Select the transition:

   • In diagram mode, select the transition arrow.

   • In text mode, select the transition's name from the Transitions (id) column.

4. Open the post functions tab:

   • In diagram mode, click Post functions in the properties panel to show the triggers configured for the transition.

   • In text mode, select the Post functions tab.

5. Click Add post function.

6. Add the post function and choose Publish Draft to finalize your changes.

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).

Use 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 a work item is created. The initial transition is called 'Create' (if you created a blank workflow) or 'Create work item' (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:

1. Create the work item.

2. Fire an event that can be processed by the listeners.

The following optional post functions are available specifically for the initial transition:

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 work item 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.

Use a post function to set a field

You can use the ‘Update Work Item Field' post function to set the value of a work item’s field after a particular transition is executed.

For example, you might want a transition that moves the work item to a closed status to automatically set the 'Resolution' field.

Example: Using a post function to set the Resolution field:

1. Edit the workflow that has the transition, and drag from status to another to create a new transition.

2. Select either None or a screen that does not contain the Resolution field.

3. Add a new "Update Work Item Field" post function and select a resolution from the Work Item Field and Field Value lists.

To create a transition that clears the Resolution field, follow the same steps above for adding an 'Update Work Item 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 work item will be cleared.

Each time one of these transitions is executed, the Resolution of the work item is automatically set or cleared, as specified in these post functions.

Use 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 work item’s project and identify the users associated with the fired event;

• Send an email notification to each user.

Example: Use a post function to fire the Generic Event to send email notifications:

1. Create or edit your transition.

2. Click the transition's Post Functions tab and edit the 'Fire an event that can be processed by the listeners' post function.

3. Select Generic Event from the list of events.

Use a post function to update the Team field

When using the Team field with advanced work item workflows, you must use the Team UUID value instead of the team name. 

To add a post function which updates the Team field:

1. Select Update Work Item Custom Field from the Add Post Function screen.

2. Select Add.

3. From the Work Item Custom Field dropdown, select Team.

4. For Custom Field Value, you must enter the Team UUID.

To get the Team UUID:

1. Go to the team profile page.

2. Copy the value of the Team UUID from the URL. For example: https://yoursite.atlassian.net/people/team/[TeamUUID]

3. Paste the Team UUID to Custom Field Value.

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:

1. Select a transition in the diagram.

2. Click Properties.

3. Either:

   • Add a new property to the transition.

   • Delete a property, by clicking the icon to the right of the 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.

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:

1. 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.

2. Create the second global transition on any other step that does not currently have a global transition pointing to it.

3. Then from text editor, select the second global transition that you created.

4. Click Edit and change the destination step to the same step you selected for your first global transition. 

5. When you're done, click Update.