Workflow Condition

This module defines a condition that can be added to workflow transitions (see: Advanced workflow configuration).

Conditions control whether the user can execute a transition. If a condition fails, the user won't be able to execute the transition. For example, the user won't see the transition button on the View issue page.

Conditions added by apps are implemented with Jira expressions that are provided upfront in the descriptor or built dynamically on the configuration page.

A workflow condition only evaluates to true if the provided Jira expression evaluates to true. It will evaluate to false in all other cases, including:

  • The Jira expression fails to evaluate because of errors.
  • The Jira expression returns anything other than a boolean value.
  • The app providing the workflow condition is uninstalled.

Configuration

Often, workflow conditions will require some degree of configuration of their behavior. For example, you may want to allow a state transition only if the issue has a particular label, and you want the project administrator to configure that label. For this purpose, three additional URLs in the descriptor allow you to declare the pages that will show:

  • the form that is shown when a workflow condition is first created.
  • the form that is shown when a workflow condition is edited.
  • the read-only view or summary of the configuration.

All URLs must be relative to the base URL of the Connect app.

Creating and editing a condition

The create and edit pages should present a form with configuration relevant to the condition. In order to persist this information in Jira, the page needs to use the javascript API, as shown below:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
  AP.require(["jira"], function(jira) {
      // When the configuration is saved, this method is called. Return the configuration based on your input elements.
      jira.WorkflowConfiguration.onSave(function() {
          var config = {
              "key": "val"
          };
          return JSON.stringify(config); // object returned here will be available under the `config` context variable in the Jira expression
      });

      // Validate any appropriate input and return true/false
      jira.WorkflowConfiguration.onSaveValidation(function() {
          return true;
      });
  });

When evaluating the condition, configuration saved that way will be available to the Jira expression under the config context variable.

Additionally, instead of just providing an additional context variable, you can override the entire Jira expression from the descriptor. To do that, include the "expression" property in the returned object, for example:

1
2
3
4
5
6
7
8
9
 AP.require(["jira"], function(jira) {
    jira.WorkflowConfiguration.onSave(function() {
        var config = {
            "expression": "dynamically built expression"
        };
        return JSON.stringify(config);
    });
});

Context variables

The following context variables are available to expressions:

  • user (User): The user the condition is evaluated for.
  • app (App): The app that provided the condition.
  • issue (Issue): The issue selected for transition.
  • project (Project): The project the issue belongs to.
  • transition (Transition): The transition that the condition is being evaluated against.
  • workflow (Workflow): The workflow that contains the condition.
  • config (JSON): The configuration saved on the configuration page using the javascript API.
  • groupOperator (String): The logical operator for a group the condition belongs to. Possible results are: AND, OR, or null. null is returned if the condition is the only condition in the transition.

Additionally, these are available for Jira Service Desk transitions:

  • customerRequest (CustomerRequest): The customer request selected for transition.
  • serviceDesk (ServiceDesk): The service desk the customer request belongs to.

Condition example

The following example declares a condition for a transition. The condition only allows the transition if:

  • The saved configuration object has a property allowedIssueTypes which is a list of numbers.
  • The issue type ID is included in the list from the configuration.

The example uses the issue context variable to get the current issue type and the config context variable to retrieve the list of allowed issue types from the saved configuration.

For a full end-to-end example of how to use and implement configuration pages, see the Workflow Condition and Validators Example app.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
  "modules": {
    "jiraWorkflowConditions": [
      {
        "description": {
          "value": "This conditions allows the transition only if the issue is one of the configured issue types."
        },
        "expression": "config.allowedIssueTypes.includes(issue.issueType.id)",
        "view": {
          "url": "/view"
        },
        "edit": {
          "url": "/edit"
        },
        "create": {
          "url": "/create"
        },
        "name": {
          "value": "Issue type is valid"
        },
        "key": "workflow-condition-example"
      }
    ]
  }
}

Properties

expression
Type
Required
Yes
Description

The Jira expression used to evaluate the condition. Must return a boolean value.

This expression can be overridden using the configuration page. If you return configuration with property "expression", then that expression will be used to evaluate the condition instead of the expression defined here. For example:

1
2
3
4
5
6
7
8
AP.require(["jira"], function(jira) {
    jira.WorkflowConfiguration.onSave(function() {
        var config = {
            "expression": "dynamically built expression"
        };
        return JSON.stringify(config);
    });
});

key
Type
Max length
100
Required
Yes
Pattern
^[a-zA-Z0-9-]+$
Description

A key to identify this module.

This key must be unique relative to the add on, with the exception of Confluence macros: Their keys need to be globally unique.

Keys must only contain alphanumeric characters and dashes.

The key is used to generate the url to your add-on's module. The url is generated as a combination of your add-on key and module key. For example, an add-on which looks like:

1
2
3
4
5
6
7
8
9
{
    "key": "my-addon",
    "modules": {
        "configurePage": {
            "key": "configure-me",
        }
    }
}

Will have a configuration page module with a URL of /plugins/servlet/ac/my-addon/configure-me.


name
Type
Required
Yes
Description

A human readable name.

Represents a string that can be resolved via a localization properties file. You can use the same i18n Property key and value in multiple places if you like, but identical keys must have identical values.

Example

1
2
3
4
{
  "value": "My text"
}

Properties

value
Type
Max length
1500
Required
Yes
Description

The human-readable default value. This will be used if no translation exists. Only the following HTML tags are supported: b, i, strong, em, and code.

i18n
Type
Max length
300
Description

The localization key for the human-readable value. Translations for the keys are defined at the top level of the add-on descriptor.


create
Type
Description

The relative URL to the app page that allows to configure the workflow condition on creation.

Properties

url
Type
Format
uri-template
Required
Yes

description
Type
Description

The description of the workflow condition. This will be presented to the user when they add a new condition to a Jira workflow.

Represents a string that can be resolved via a localization properties file. You can use the same i18n Property key and value in multiple places if you like, but identical keys must have identical values.

Example

1
2
3
4
{
  "value": "My text"
}

Properties

value
Type
Max length
1500
Required
Yes
Description

The human-readable default value. This will be used if no translation exists. Only the following HTML tags are supported: b, i, strong, em, and code.

i18n
Type
Max length
300
Description

The localization key for the human-readable value. Translations for the keys are defined at the top level of the add-on descriptor.


edit
Type
Description

The relative URL to the app page that allows to configure the workflow condition once it exists.

The edit URL can contain the following context parameters:

  • condition.id: The unique identifier of the condition.
  • condition.config: The configuration value saved to Jira after calling WorkflowConfiguration.onSave.

Properties

url
Type
Format
uri-template
Required
Yes

evaluationContext
Type
Allowed values
  • user
  • USER
  • app
  • APP
Description

EXPERIMENTAL. Controls how to run the expression during the transition.

  • user: The expression will be evaluated in the context of the user making the transition (default).
  • app: The expression will be evaluated in the context of the app user.

    If the expression needs to perform some operations which require permissions that the user making the transition might not have, choose app and make sure that your app has appropriate scopes.

    Note: regardless of the value selected here, the user variable in the expression always points to the user that performs the transition.


view
Type
Description

The relative URL to the app page that shows the read-only configuration or summary of the workflow condition.

The view URL can contain the following context parameters:

  • condition.id: The unique identifier of the condition.
  • condition.config: The configuration value saved to Jira after calling WorkflowConfiguration.onSave.

Properties

url
Type
Format
uri-template
Required
Yes