Advanced Workflow Configuration

This section covers advanced topics on workflow transitions, including built-in JIRA conditions, combining conditions into groups, and applying validators and post functions. These are topics that are best explored once you've mastered the basics. To get started with workflow configuration, see Configuring Workflow.

What are conditions, validators, and post functions?

Before we get into the details, it's probably helpful to cover a few basics.

Conditions

Conditions control who can perform a transition and the circumstances under which they can perform the transitions, such as their project permissions, the status of any sub-tasks, or the state of source code associated with issues.

If any part of a transition's condition fails, the user will not see the transition link on the 'view issue' page.

Validators

Validators check that any input made to the transition is valid before the transition is performed. For example, validators can be used to ensure that comments on a transition's screen meet a certain project permission criterion.

If a transition's validator fails, the transition's post functions are not executed. When this happens the issue does not progress to the destination step of the transition.

JIRA ships with a couple of default validators that check whether or not the user who performed a transition had the necessary project permission, which can be added immediately to any transition.

(info) You can also create your own validators via the plugin system. See the Workflow Plugin Modules for details.

How do validators differ from conditions?

  • Conditions are used to determine whether an issue's transition can be executed by a particular user, including a range of other circumstances such as the user's project permissions and the current state of the issue. However, conditions cannot validate input parameters provided by the user on the transition's screen, since if a condition fails, the user is prevented from executing the transition.
  • 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.

Post functions

Post functions carry out any additional processing required immediately 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 such as an email notification

There are two categories of post functions in JIRA — essential and optional – which are described later in this page.

JIRA's built-in conditions

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

Condition

Description

Additional Parameters Required

Only Assignee Condition

Only allow the issue's current assignee to execute the transition.

None

Only Reporter Condition

Only allow the issue's reporter to execute the transition.

None

Permission Condition

Only allow users with a given permission to execute the transition.

A project-wide permission

Sub-Task Blocking Condition

Only allow a parent issue's transition to execute if all its sub-tasks have at least one of a specified set of statuses.

One or more statuses

User Is In Group

Only allow users in a given group to execute the transition.

A group

User Is In Group Custom Field

Only allow users in a given group-type custom field to execute a transition.

A custom field of type "Group"

User Is In Project Role

Only allow users in a given project role to execute a transition.

A project role

Code Committed Condition

Only allow the transition to execute if code either has or has not been committed against the issue.

Specify whether or not code must be committed

No Open Reviews Condition

Only allow the transition to execute if no related Crucible reviews are open against the issue.

None

Unreviewed Code Condition

Only allow the transition to execute if no unreviewed changesets related to the issue exist.

None

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

Adding a condition

To add a condition to a transition:

  1. Log in as a user with the JIRA Administrators global permission.
  2. Choose the cog icon  at top right of the screen, then choose Issues. Select Workflows to open the 'Workflows' page, which shows a list of all existing workflows in your system.
  3. Click the Edit link next to the workflow with the transition you wish to change.
  4. Use either Diagram or Text edit mode to add the condition to the transition.
    • Using Diagram edit mode to add the condition to the transition:
      1. Move the mouse pointer over the relevant transition label and click the cog icon that appears to the right of the label to reveal a popup menu.
      2. From the popup menu, select View Conditions to view the transition's existing conditions.
    • Using Text edit mode to add the condition to the transition:
      1. In the Transitions (id) column, click the name of the relevant transition. The Transition page is displayed.
      2. Click the Conditions tab (if not already selected) to see a list of the transition's existing conditions.
  5. In the Conditions tab, click Add. A list of all available conditions is displayed (see JIRA's built-in conditions).
  6. Select a condition from the list and click Add. If the condition requires additional parameters – e.g. the name of a group or project role – the Add Parameters To Condition dialog box/page is displayed.
    • Specify your criteria on the Add Parameters To Condition dialog box/page and click Add. (Some criteria may require more than one step.)
  7. The Conditions tab is displayed again, showing your new condition at the bottom of the list of conditions. From here, you can:
    • Click the Edit link next to the condition's name to edit its additional parameters, if applicable.
    • Click the Delete link next to the condition's name to remove the condition.
    • Combine your conditions into AND/OR groups. See Combining conditions into groups.

Combining conditions into groups

You can construct complex conditions by combining two or more 'individual conditions' – added using the procedure above – using AND/OR boolean logic to form a grouped condition. For example, you can construct the following simple grouped condition:

  • Only the assignee of this issue can execute this transition
    AND
  • Only users in group jira-users can execute this transition

This grouped condition is only true if the user is the assignee of the issue AND the same user is in the jira-users group.

An overall complex condition can be constructed for your transition by combining multiple grouped conditions using AND/OR boolean logic or nesting grouped conditions. A transition with a complex condition can only be executed if all individual and grouped conditions have been satisfied.

Converting an individual condition into a grouped condition

Use this procedure to create grouped conditions out of individual conditions that are already part of another grouped condition. This allows you to nest grouped conditions.

It is not possible to add an individual condition that is separate from the outermost grouped condition. Clicking the Add button only adds an individual condition to the outermost grouped condition, refer to JRA-25179 for more information.

To convert an individual condition into a grouped condition:

  1. Follow the Adding a condition procedure (above) to step 3.
  2. Instead of clicking Add at step 4, click Add grouped condition for the individual condition you wish to convert into a grouped condition.
  3. Continue on from step 5.
    (info) Note: If you only have a single individual condition on the 'Conditions' tab, the 'Add grouped condition' link is not available; just click the Add button to create your grouped condition.

To add an individual condition to a grouped condition:

  1. Follow the Adding a condition procedure (above) to step 3.
  2. Instead of clicking Add at step 4, click Add condition to group for the grouped condition to which you want to add your individual condition.
  3. Continue on from step 5.

Switching a grouped condition's logic

The logic of all individual conditions within a grouped condition can be switched between AND and OR. To do this, click the Switch to OR or Switch to AND link associated with the grouped condition you wish to change.

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

Adding a validator

To add a validator to a transition:

  1. Log in as a user with the JIRA Administrators global permission.
  2. Choose the cog icon  at top right of the screen, then choose Issues. Select Workflows to open the 'Workflows' page, which shows a list of all existing workflows in your system.
  3. Click the Edit link next to the workflow with the transition you wish to change.
  4. Use either  Diagram or Text edit mode to add the validator to the transition.
    • Using Diagram edit mode to add the validator to the transition:
      1. Move the mouse pointer over the relevant transition label and click the cog icon that appears to the right of the label to reveal a popup menu.
      2. From the popup menu, select View Validators to view a list of the transition's existing validators.
    • Using Text edit mode to add the validator to the transition:
      1. In the Transitions (id) column, click the name of the relevant transition. The Transition page is displayed.
      2. Click the Validators tab to display a list of the transition's existing validators.
  5. In the Validators tab, click Add. A list of all available validators is displayed.
  6. Select a validator from the list and click Add. If the validator requires additional parameters – e.g. the name of a group or project role – the Add Parameters To Validator dialog box/page is displayed.
    • Specify your criteria on the Add Parameters To Validator dialog box/page and click Add.
  7. The Validators tab is displayed again, showing your new validator at the bottom of the list. From here, you can:
    • Click the Edit link next to the validator's name to edit its additional parameters, if applicable.
    • Click the Delete link next to the validator's name to remove the validator.

(info) Note:

  • The only logical relationship between multiple validators applied to a transition is AND.
  • Unlike Conditions, it is not possible to create grouped validators or to change the logical relationship between multiple validators.

Post functions

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 step.
  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. Re-index 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 the following optional post functions, which can be added to transitions:

Optional post function

Description

Assign to Current User

Assigns the issue to the user who is executing the transition.

(info) Note: This post function is ignored unless the user has the Assignable User permission. Use a condition to ensure that the logged-in user has 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

Fires 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

(info) Note: This post function cannot update custom fields.

(info) Notes:

  • The six optional post functions must be positioned before the Update change history for an issue and store the issue in the database post function (above), with the exception of the Create transition.

  • Depending on your particular JIRA installation and installed plugins, other post functions may be available.
  • You can create your own post functions using the plugin system; see the Workflow Plugin Modules for details.

The initial transition ('Create' or 'Create Issue')

When creating an issue, it is sometimes useful to perform specific processing tasks (such as setting a particular field's value). You can do this by adding post functions to the workflow's initial transition.

The initial transition is executed whenever a user creates an issue, which in turn, places the newly-created issue into the workflow's initial step. Every workflow has only one initial step, which is the first step in the issue's workflow and is the first incoming transition. By default:

  • The initial transition is called Create (if you created a blank workflow) or Create Issue (if you copied the system workflow).
  • The initial step is called Open after having created a workflow above.

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

Fire an event that can be processed by the listeners. (Not available in On Demand.)

The optional post functions (above) can also be added to a workflow's initial transition, as well as the following optional post functions (which, with the exception of Store Issue, are essential to all other newly-created transitions):

Optional post function (initial transition only)

Description

Create Comment

Adds a comment to an issue if one is entered during a transition.

Re-index Issue

Re-indexes an issue to keep JIRA's indexes in sync with the database.

Update Issue Status

Sets the issue's status to the linked status of the destination workflow step.

Store Issue

Stores updates to an issue (no change history is created).

(warning) Currently, there is a JIRA bug (JRA-25070) that prevents these optional post functions from being deleted once they have been added.

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.

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.

(warning) However, keep 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 (e.g. Version or Component).

Adding a post function

To add a post function to a transition:

  1. Log in as a user with the JIRA Administrators global permission.
  2. Choose the cog icon  at top right of the screen, then choose Issues. Select Workflows to open the 'Workflows' page, which shows a list of all existing workflows in your system.
  3. Click the Edit link next to the workflow whose transition you wish to add a post function to.
  4. Use either Diagram or Text edit mode to add the post function to the transition.
    • Using Diagram edit mode to add the post function to the transition:
      1. Move the mouse pointer over the relevant transition label and click the cog icon that appears to the right of the label to reveal a popup menu.
      2. From the popup menu, select View Post Functions to view a list of the transition's existing post functions.
    • Using Text edit mode to add the post function to the transition:
      1. In the Transitions (id) column, click the name of the relevant transition. The Transition page is displayed.
      2. Click the Post Functions tab and a list of the transition's existing post functions is displayed.
    A copied system workflow (above) has the following built-in post functions for the Start Progress transition:
  5. Click the Add link (in the Post Functions tab). A list of all available post functions is displayed.
  6. Select a post function from the list and click the Add button.
  7. If the post function requires one or more configuration parameters (e.g. the name of an event), the Add Parameters To Function dialog box/page is presented. Enter the appropriate information and click the Add button.
  8. The Post Functions tab is displayed again, showing your new post function at the bottom of 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.

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(s) after a particular transition is executed.

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

For a particular step in a workflow, you might need to create a transition that moves the issue to a 'closed' status (e.g. Close, Resolved, etc) - see open and closed issues. As part of this transition, you might want to automatically set the Resolution field. To do this:

  1. Create or edit your transition.
    • In the Transition View field on the Add Transition dialog box or the Add/Update Workflow Transition page, select either No View For Transition or the screen that does not contain the Resolution field.
  2. Add a new post function of type Update Issue Field.
  3. Do the following on the Add Parameters to Function page:
    1. Select Resolution from the Issue Field select list.
    2. Select a suitable resolution from the Field Value select list.
  4. Click the Add button and the transition's list of post functions is displayed with your added post function highlighted in blue:

(info) 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, on the Add Parameters To Function page, 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.

(info) 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 (above).
  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.
      (info) 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.

(info) 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 customise 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:

  1. Log in as a user with the JIRA Administrators global permission.
  2. Choose the cog icon  at top right of the screen, then choose Issues. Select Workflows to open the 'Workflows' page, which shows a list of all existing workflows in your system.
  3. Click the Edit link next to the workflow whose transition's properties you wish to view or edit.
  4. Use either Diagram or Text edit mode to view or edit the properties of a transition.

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

  1. Move the mouse pointer over the relevant transition label and click the cog icon that appears to the right of the label to reveal a popup menu.
  2. From the popup menu, select Transition Properties, which opens the Edit Properties dialog box that allows you to view a list of the transition's existing properties and edit them.

    On the Edit Properties  dialog box, you can:
    • Add a new property to the transition.
    • Edit a property's key or value, by simply clicking the property's key or value to begin editing it.
    • 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, click the name of the relevant transition. The Transition page is displayed.
  2. Click the 'View properties of this transition' link. The View Workflow Transition Properties page is displayed listing the properties currently set up for the transition. You can this page to add and delete properties for this transition.
    (info) 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.

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

Customising workflow transitions

When viewing an issue, most of the operations and workflow transitions accessible to a user are available from a row of buttons towards the top of the issue, known as the operations bar. As shown in the following screenshot, workflow transitions appear in the right-most set of buttons of the operations bar.


Screenshot: Workflow transitions on the 'view issue' page


By default, the first two transitions appear as separate buttons in the set of transition buttons. Any additional transitions 'spill over' into the Workflow button dropdown menu. The order in which these buttons appear on the view issue page is based on the order of the system workflow, or for custom workflows, the order in which a JIRA administrator has added transitions to the custom workflow.

Hence, in the example above, the workflow transition order is: Start Progress -> Resolve Issue -> Close Issue.

JIRA provides the ability to customise the appearance and order of these transitions on the View Issue page.

To change the number of transition buttons from the default of two (with any remaining transitions spilling over into the 'Workflow' button dropdown menu):

  1. Shutdown JIRA.
  2. Edit the jira-config.properties file in your JIRA Home Directory.
    (info) 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.
    (info) 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 and 'workflow' menu items

To change the order of transition buttons, including additional transitions in the Workflow dropdown menu on the View Issue page, you need to add the property key opsbar-sequence to each workflow transition that you wish to re-order. 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 (above).
  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.
    (tick) 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.

Working with 'common transitions'

A 'common transition' is a transition that is defined only once in a given workflow but is used more than once in the same workflow. A common transition has more than one originating step leading to a single destination step, but provides the added advantage of only requiring you to edit or update the transition in one place.

(info) Please Note: Global transitions (above) are similar to common transitions and provide the same editing advantages. However, they differ from each other in the following respects:

  • For common transitions, the destination step of the transition has only a subset of the remaining steps in the workflow as incoming steps.
  • For global transitions, the destination step of the transition has all remaining steps in the workflow as incoming steps. Be aware that global transitions can only be deleted in Diagram edit mode (above).

You can turn an ordinary transition into a common transition in 'Diagram' edit mode by following these steps:

  1. (Optional) Create a transition from one (target) step to another (destination) step as described in Adding a transition (above).
  2. Create another transition from a different target step to the same destination step in step 1, but in the Add Transition dialog box, choose the Use Common Transition option.
  3. In the Transition To Reuse dropdown menu, select the transition you created in step 1 above or, if you did not perform step 1, select an existing ordinary transition (which also leads to the same destination step) from this dropdown menu.

(info) You can edit existing common transitions in Text edit mode, but as described in Adding a transition (above), they cannot be created from this page — only in Diagram edit mode.

If you are only able to use Text edit mode to create or edit workflows, you can do either of the following to edit common transitions in a JIRA workflow:

  • Copy the system workflow — the system workflow contains common transitions (e.g. Start Progress, Resolve Issue, Close Issue). Although you cannot edit the system workflow, you can copy it and then edit its steps and transitions (via XML) to suit your requirements.
  • Create your workflow in XML — see Using XML to create a workflow (below).

Using XML to create a workflow

JIRA's workflow editor generates OSWorkflow XML definition files that are stored in JIRA's database. If you need to take advantage of an OSWorkflow-based feature that is not available in JIRA's workflow editor (such as 'common transitions' above), you can define the workflow in XML and then import it into JIRA as described below.

Once the XML workflow has been imported, JIRA's workflow editor should be able to display most OSWorkflow definitions even if it does not support creating or editing them.

For example, conditional results of workflow transitions are displayed in the Other tab on the 'View Workflow Transition' page.

(info) The Other tab is only visible if a transition has elements that the editor does not directly support.

Importing an XML workflow into JIRA

To import an XML workflow into JIRA:

  1. Log in as a user with the JIRA System Administrators global permission.
  2. Choose the cog icon  at top right of the screen, then choose Issues. Select Workflows to open the 'Workflows' page, which shows a list of all existing workflows in your system.
  3. Click the Import from XML button to open the Import Workflow dialog box.
  4. In the Name field, type a name (usually 2-3 words) to identify your new workflow.
  5. (Optional) In the Description field, type a detailed description of your new workflow.
  6. For the Workflow Definition  option, you can do either of the following:
    • Upload an XML workflow definition file — to do this, choose the Provide a full path to an XML file... option and in the File Path field, type the full path to your XML workflow definition file.
      (warning) This path must be local one, so your XML workflow definition file must be located on your JIRA server.
    • Paste the contents of an XML workflow definition file into JIRA — to do this, choose the Paste the workflow XML definition option, copy the contents of your XML workflow definition file and in the Workflow Definition (XML) field, paste this copied content.
  7. Click the Import button.

Copying a workflow between systems

Sometimes it is useful to create a workflow in a test system and then copy it into a production system. To do this:

  1. In the test system, export the workflow to XML by clicking the XML link next to the workflow in the list shown on the View Workflows page (above) and save the output into a file.
  2. In the production system, import the file via the 'import a workflow from XML' link as described in Using XML to create a workflow (above).

(minus) When importing an XML workflow into JIRA:

  • JIRA's XML workflow definitions contain references to JIRA meta attributes. For example, the id of the linked JIRA status of each workflow step is stored as a 'jira.status.id' meta attribute in the step's definition. Therefore, when manually creating workflows in XML, please ensure that all referenced external entities exist before you import the workflow into JIRA.

(minus) When copying a workflow between systems:

  • Please note that conditions, validators and post functions can have parameters that might be valid in one system and not in another. For example, different systems might contain different sets of values for the 'Resolution' field (since it is possible to define your own values). This would be a problem if the 'Update Issue Field' post function is used to set the 'Resolution' field to a value that exists in one system but not the other.
Last modified on Jul 12, 2014

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.