Workflow Validator

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

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 issue does not progress to the destination status of the transition, the transition's post functions are not executed and the error message of the failed validator is shown.

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

A workflow validator 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 validator is uninstalled.

Configuration

Often, workflow validators 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 validator is first created.
• the form that is shown when a workflow validator 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 validator

The create and edit pages should present a form with configuration relevant to the validator. 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

  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 validator, 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

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 evaluating the validator.
• app (App): The app that provided the validator.
• issue (Issue): The issue that is about to be transitioned. Includes changes made on the transition screen.
• project (Project): The project the issue belongs to.
• transition (Transition): The transition that the validator is being evaluated against.
• config (JSON): The configuration saved on the configuration page using the javascript API.

Additionally, these are available for Jira Service Desk transitions:

• customerRequest (CustomerRequest): The customer request that is about to be transitioned.
• serviceDesk (ServiceDesk): The service desk the customer request belongs to.

Validator example

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

• The saved configuration object has a string property named "format-regex".
• The issue has a summary that matches the regular expression from the configuration.

The example uses the issue context variable to get the summary of the current issue and the config context variable to retrieve the regular expression 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
27
28

{
  "modules": {
    "jiraWorkflowValidators": [
      {
        "description": {
          "value": "This validator will allow the transition only if the summary has the configured format."
        },
        "expression": "issue.summary.match(config['format-regex']) != null",
        "errorMessage": {
          "expression": "'Issue summary has to be in the following format: ' + config['format-regex']"
        },
        "view": {
          "url": "/view"
        },
        "edit": {
          "url": "/edit"
        },
        "create": {
          "url": "/create"
        },
        "name": {
          "value": "Summary has the correct format"
        },
        "key": "workflow-validator-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);
    });
});