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

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);
    });
});

1
2
3
4
5
6
7
8
9

{
    "key": "my-addon",
    "modules": {
        "configurePage": {
            "key": "configure-me",
        }
    }
}

1
2
3
4

{
  "value": "My text"
}

1
2
3
4

{
  "value": "My text"
}