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 or string value.
  • The app providing the workflow validator is uninstalled.
If the expressions returns a string value, that value will be shown as the error message on the transition.

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
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 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
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 who performs the transition.
  • 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.
  • originalIssue (Issue): The issue before changes were made on the transition screen.
  • project (Project): The project the issue belongs to.
  • transition (Transition): The transition that the validator is being evaluated against.
  • workflow (Workflow): The workflow that contains the validator.
  • 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
29
{
  "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

errorMessage
Type
Required
Yes
Description

The error message that will be shown if the validator rejects the transition by returning false.

This can be either a static i18n property, or an object containing the "expression" property, with a Jira expression that returns the error message dynamically, based on the current transition or configuration.


expression
Type
Required
Yes
Description

The Jira expression used to evaluate the validator. Must return a boolean or string 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 validator 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 validator on creation.

Properties

url
Type
Format
uri-template
Required
Yes

description
Type
Description

The description of the workflow validator. This will be presented to the user when they add a new validator 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 validator once it exists.

The edit URL can contain the following context parameters:

  • validator.id: The unique identifier of the validator.
  • validator.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 the expression is run during the transition:

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

    If the expression performs operations that require permissions but the user making the transition cannot be guaranteed to have those permissions, choose app and make sure that your app has the 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 validator.

The view URL can contain the following context parameters:

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

Properties

url
Type
Format
uri-template
Required
Yes