• About Jira Software modules
  • Admin Page
  • Administration UI locations
  • Boards
  • Build
  • Dashboard Item
  • Deployment
  • Development Tool
  • Dialog
  • Entity Property
  • Feature Flag
  • Global Permission
  • Home container
  • Issue Background Script
  • Issue Content
  • Issue Field
  • Issue Glance
  • Issue view UI locations
  • Keyboard Shortcut
  • Page
  • Project Admin Tab Panel
  • Project Page
  • Project Permission
  • Project settings UI locations
  • Project sidebar
  • Remote Link
  • Report
  • Search Request View
  • Tab Panel
  • Time Tracking Provider
  • User profile menu
  • Web Item
  • Web Panel
  • Web Section
  • Webhook
  • Workflow Condition
  • Workflow Post Function
  • Workflow Validator

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

errorMessage

Type
object
Required
Yes
Description

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

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
string
Required
Yes
Description

The Jira expression used to evaluate the validator. 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 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
string
Max length
100
Required
Yes
Pattern
^[a-zA-Z0-9-]+$

name

Type
object
Required
Yes

create

Type
object
Description

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


description

Type
object
Description

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


edit

Type
object
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.

evaluationContext

Type
string
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.


    view

    Type
    object
    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.

    • System status
    • Privacy
    • Developer Terms
    • Trademark
    • Cookie Preferences
    • © 2019 Atlassian