Advanced workflow configuration

What are conditions, validators, and post functions?

Before we get into the details, let's cover a few basics.

Workflow transition screen, displaying the statuses that use this transition (at the top) as well as the conditions available (at the bottom)

How do conditions differ from validators?

• Conditions are used to determine whether an issue's transition can be executed by a particular user. However, conditions cannot validate input parameters provided by the user on the transition's screen.
• Validators have access to any input available to the transition – such as input gathered from the user on a transition's screen – and thus, can validate this input.

JIRA's built-in conditions

JIRA includes the following individual conditions, which can be added immediately to any transition:

You can also create your own conditions via the plugin system. See the Workflow Plugin Modules for details.

Adding a condition

This procedure documents adding a condition using the Diagram edit mode. For text mode, see this procedure instead.

To add a condition to a transition using diagram edit mode:

1. Log in as a user with the JIRA Administrators global permission.
2. Choose > Issues. Select Workflows to open the Workflows page, which displays all of the workflows in your system.
3. Click the Edit link next to the workflow with the transition you wish to change.

4. Select the transition in the diagram, as shown here:

   Transition selected (see blue arrow in diagram)	Properties panel for selected transition ("Start Progress")

5. Click on Conditions to open this screen:
   
6. Click Add condition to display a list of conditions that can be added to the transition. Select a condition from the list and click Add.
7. If required, select parameters to add to the condition (as shown here). When finished, click Add.
   

Your new condition is displayed on the Workflow transition screen:

To add a condition to a transition using text edit mode:

1. Follow steps 1 through 3 as outlined above.
2. In the Transitions (id) column, click the name of the relevant transition. The Workflow transition screen is displayed.
3. Click the Conditions tab (if not already selected) to see a list of the transition's existing conditions.
4. Follow steps 6 and 7 as outlined above.

Combining conditions into groups

You can construct complex conditions by combining two or more individual conditions using the procedure above, or by creating a grouped condition, as described below. You can also combine multiple grouped conditions by nesting grouped conditions. A group can be configured to be successful either when all the conditions in the group are successful (use All of the following conditions ) or when at least one of the conditions in the group are successful (use Any of the following conditions ). 

Converting an individual condition into a grouped condition

Use this procedure to create grouped conditions.

To convert an individual condition into a grouped condition:

1. Follow the Adding a condition procedure to step 3.
2. Select the Add grouped condition icon for the individual condition you wish to change, as shown here:
   
3. Select a new condition and click Add.
4. If required, select parameters to add to the condition (as shown here). When finished, click Add.

Your grouped condition is displayed as follows:

Switching a grouped condition's logic

The logic of all individual conditions within a grouped condition can be switched between All of the following conditions and Any of the following conditions. To do this, switch the link (as shown below) for any condition you wish to change.

If you need to switch the logic of some, but not all, individual conditions within a grouped condition, create a nested grouped condition (as described above) instead.

Adding a validator

This procedure documents adding a validator using the Diagram edit mode. For text mode, see this procedure instead.

To add a validator to a transition:

1. Follow the Adding a condition procedure to step 4.
2. At step 5, click Validators from the displayed Properties panel.
3. Click Add validator to display a list of validators that can be added to the transition. Select a validator from the list and click Add.
4. If required, select parameters to add to the validator. When finished, click Add.

Your validator is displayed as follows:

To add a validator to a transition using text edit mode:

1. Follow steps 1 through 3 from the Adding a condition procedure.
2. In the Transitions (id) column, click the name of the relevant transition. The Workflow transition screen is displayed.
3. Click the Validators tab to see a list of the transition's existing validators.
4. Follow steps 3 and 4 as outlined directly above.

Post functions

• Essential post functions
• Optional post functions
• The initial transition
• Adding a post function
• Using a post function to set a field
• Using a post function to send HipChat notifications
• Using a post function to send email notifications

Essential post functions

JIRA includes the following essential post functions, which are automatically added to every newly-created transition and performed in this order:

1. Set issue status to the linked status of the destination workflow status.
2. Add a comment to an issue if one is entered during a transition.
3. Update change history for an issue and store the issue in the database.
4. Reindex an issue to keep indices in sync with the database.
5. Fire an event that can be processed by the listeners.

These essential post functions cannot be deleted from a transition or reordered relative to each other, as this could compromise other issue functionality within JIRA. However, you can insert other (optional) post functions between them.

Optional post functions

JIRA includes optional post functions (described below), which can be added to transitions. There may be additional post functions available, depending on your particular JIRA installation and installed plugins. Additionally, you can create your own post functions using the plugin system; see the Workflow Plugin Modules for details.

Optional post function	Description
Assign to Current User	Assigns the issue to the user who is executing the transition. Note: This post function is ignored unless the user has the Assignable User permission. Create a condition to give the logged-in user this permission before 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. Before you can use this post function, you must first have configured your JIRA installation with HipChat. See Configuring JIRA with HipChat 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: Assignee Description Environment Priority Resolution Summary Original Estimate Remaining Estimate Note: This post function cannot update custom fields and must be positioned after the other optional post functions.

The initial transition

You can add post functions to a workflow's initial transition in cases where you need to perform specific processing tasks – such as setting a particular field's value – when creating an issue. 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. These post functions are automatically added to the initial transition of each newly-created workflow (and performed in this order): Essential post function (initial transition only) Creates the issue Fires an event that can be processed by the listeners

The optional post functions listed above can be added to a workflow's initial transition, in addition to the following post functions.

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

Optional post functions added to the workflow's Create transition (for example, an Update Issue Field post function to set the Assignee field to a particular user), must be placed before the Creates the issue originally post function. If you wish to, you can configure the initial status for your workflow to go to a different initial transition. See Configuring the initial status for details.

Special Cases

If you need to set the Resolution field when creating an issue, add the Update Issue Field post function after the Creates the issue originally 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, keep the use of the Store Issue post function to a minimum, since this post function:

• does not generate change history
• is incapable of persisting fields that have a one-to-many relationship with the issue (for example, Version or Component)

Adding a post function

This procedure documents adding a post function using the Diagram edit mode. For text mode, see this procedure instead.

To add a post function to a transition:

1. Follow the Adding a condition procedure to step 4.
2. At step 5, click Post Functions from the displayed Properties panel.
3. Click Add post function to display a list of post functions that can be added to the transition. Select a post function from the list and click Add.
4. If required, select parameters to add to the validator. When finished, click Add.
5. The Post Functions tab is displayed again, showing your new post function in the list. From here, you can:
   
   • Click the Edit link next to the post function's name to edit its configuration parameters (if there are any).
   • Click the Move Up link to move the post function higher up in the list (i.e. it will be executed earlier).
   • Click the Move Down link to move the post function lower down in the list (i.e. it will be executed later).
   • Click the Delete link next to the post function's name to remove the post function.

Hover your mouse over the outlined area in the post function display box to display the options for moving, editing, or deleting a post function. If the option is available for the selected post function, you will be able to select it as shown above.

 

Using Text edit mode to add the post function to the transition:

1. Follow steps 1 through 3 from the Adding a condition procedure.
2. In the Transitions (id) column, click the name of the relevant transition. The Workflow transition screen is displayed.
3. Click the Post Functions tab to see a list of the transition's existing post functions.
4. Follow steps 3 and 5 as outlined directly above.

Using a post function to set a field

You can use an Update Issue Field post function to set the value of an issue's field after a particular transition is executed.

For a particular step in a workflow, you might need to create a transition that moves the issue to a closed status. As part of this transition, you might want to automatically set the Resolution field, as described below.

Using a post function to set the Resolution field (diagram mode):

1. Log in as a user with the JIRA Administrators global permission.
2. Choose > Issues. Select Workflows to open the Workflows page, which displays all of the workflows in your system.
3. Click the Edit link next to the workflow you wish to edit.

4. Drag a port of any status to a port of another status (see the illustration below) to create a new transition between the two statuses.
   

5. In the Add Transition dialog box, select either None or a screen that does not contain the Resolution field.
   
6. Add a new post function of type Update Issue Field and do the following:
   
   1. Select Resolution from the Issue Field select list.
   2. Select a suitable resolution from the Field Value select 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 select 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 apply a JQL query to filter issues in your Notify Hipchat post function, so that if an issue transitions with this post function, but its JQL query does not retrieve that issue, the HipChat notification will not be sent.

Before you can use the Notify HipChat post function, you must first have configured your JIRA installation with HipChat. See Configuring JIRA with HipChat for more information.

 

To do this:

1. Create or edit your transition.
2. Add a new post function of type Notify HipChat.
3. Do the following on the Add Parameters to Function page:
   
   1. Specify an optional JQL query in the field provided if you want to send notifications to issues which not only pass through this transition but are also retrieved by this query.
      Leave this field empty to send notifications to all issues that pass through this transition.
   2. Select the HipChat Rooms you want to link with your workflow transition.

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

Use the Generic Event to send email notifications.

To do this:

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. On the Update parameters of the Fire Event Function for this transition page, select Generic Event from the list of events.

Working with transition properties

Properties are key-value pairs that can be used to further customize transitions. For example, transition properties help to extend a copied system workflow to allow language translations.

To view and edit the properties of a transition in diagram mode:

1. Select a transition in the diagram.
2. Click Properties option in the Properties panel to display the View Workflow Transition Properties screen shown here:
   
3. Do any of the following:
   • Add a new property to the transition.
   • Delete a property, by clicking the icon to the right of the property.
     

Using Text edit mode to view or edit the properties of a transition

1. In the Transitions (id) column of the displayed workflow, click the name of the relevant transition. The Workflow transition page is displayed.
2. Click the View Properties link at the top of the page.

It is possible to implement restrictions on transitions using transition properties. For more information, see Workflow properties.

Customizing workflow transitions

When viewing an issue, most of the operations and workflow transitions are available from a row of buttons at the top of the issue (see the illustration at the top of this page).

By default, the first two transitions appear as separate buttons in the set of transition buttons. Additional transitions appear in the Workflow button dropdown menu. The order in which these buttons appear is based on the order defined in the system workflow.

To change the number of transition buttons from the default of two:

1. Shutdown JIRA.
2. Edit the jira-config.properties file in your JIRA Home Directory.
   See Making changes to the jira-config.properties file for more information.
3. Change the value of 'X' in the ops.bar.group.size.opsbar-transitions = X property of this file to the number of transition buttons required before the Workflow button.
   If this property does not exist in your jira-config.properties file, add it. Otherwise, a default value of 2 is assumed.
4. Save the updated jira-config.properties file.
5. Restart JIRA.

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

To add an opsbar-sequence property key and value to a workflow transition:

1. Access the workflow transition's properties, as described in Working with transition properties.
2. In the Add New Property section of the workflow transition's View Workflow Transition Properties page, type opsbar-sequence into the Property Key field.
3. In the Property Value field, type a positive integer value (starting at '0') that defines the order of the transition action on issue views.
   For each workflow transition, you may wish to use gaps in your opsbar-sequence property values (for example, 10, 20, 30, etc.) rather than consecutive values. This will allow you to 'insert' new workflow transitions more easily at a later point in time.
4. Click the Add button.

Note: Be aware that 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.

Working with global transitions

Global transitions are ones that can be used by any status in a workflow, as shown here:

As of JIRA 6.2 you can select a status and check 'Allow all statuses to transition to this one'.

Reusing transitions

When adding a transition, you choose to reuse an existing transition if the destination status is the same.

1. Create a transition by selecting Add Transition.
2. When you are presented with the Add Transition dialog, select the Reuse a transition tab and make your selections:
   
3. Click Add.

Global transitions

You can add a global transition as part of the status creation step or when adding an existing status.

Creating a new status with a global transition:

1. Click Create new status.
2. In the displayed dialog, enter the status name, description, and check the Add global transition to status option.
   
3. Click Create. Your global transition and new status are available immediately:
   

You can also add a global transition this way:

1. Select a status, for example, Closed.
2. Select the Add a global transition option from the Properties panel, as shown here:
   
3. The Add Global Transition dialog is displayed. Enter a name and description, select a transition screen, and click Create.