Getting Started

JIRA Extension Points

A script validator is a powered-up version of a standard Jira validator. Instead of using one of the basic validators that you find in Jira, you can run a script to validate your issue. If the script returns false the script does not transition until all errors are resolved, for example, filling in the required fields. Validators allow administrators to determine what error message is displayed to the user. So, a scripted condition gives you more options to control this part of the workflow.

ScriptRunner for Jira Cloud provides workflow validators using the Jira Expression Framework. It is not possible to use the REST API.

There are several ways to enhance your workflow using script validators, including:

Note
Remember, a validator checks to see if the user can transition an issue, they don’t prevent the next transition button from appearing (that is a script condition).

Add Validator

  1. Select the transition you wish to add the validator to.

  2. Click Validators→Add Validator.

  3. Select the ScriptRunner Script option then Add.

  4. Enter the Name of ScriptRunner Script Validator.

  5. In the ScriptRunner Script Validator field, enter the script validator expression. This script validator must be written as a Jira expression.

  6. Type an error message to show when the validator fails in Message to Show when Validation Fails.

Tip
For help navigating to ScriptRunner workflow functions, follow the steps to navigate to workflow functions.

Edit Validator

  1. Select the transition the validator is on.

  2. Click Validators. A list of all validators on the selected transition is shown.

  3. To edit an existing validator, click the Pencil.

  4. Edit the validator and click Update.

Examples

Require One Linked Issue on Issue Creation

You have a support portal and a separate support development instance. You want to ensure that all issues created on the support development instance are linked to their corresponding user-facing ticket on the support portal. Ensure all issues created on one Jira instance are linked with their corresponding issue on another instance.

  1. Select the Create transition.

  2. Click Validators→Add Validator.

  3. Select ScriptRunner Script and click Add.

  4. Add a description of the validator in Name of ScriptRunner Script Validator for example, Require One Linked Issue.

  5. Insert the following ScriptRunner Script Validator:

      issue.links.length >0

    This validator now ensures there must be at least one linked issue when an issue is created. If there are none, an error shows.

  6. Type an error message to show when the validator fails in Message to Show when Validation Fails.

Tip
You can edit this script to make other fields required. For example replace links with fixVersions or components.

Select Lists Must be Populated

You want to enforce that issues have the required information before they are created. Specify that both select-list drop-downs in a custom cascading-select field must be populated to Create an issue.

  1. Select the Create transition.

  2. Click Validators→Add Validator.

  3. Select ScriptRunner Script and click Add.

  4. Add a description of the validator in Name of ScriptRunner Script Validator for example, Select Lists Must be Populated.

  5. Insert the following ScriptRunner Script Validator. Replace customfield_10093 in the example below with the ID of the cascading-select list field inside of your instance:

      issue.customfield_10093.child.value.length >0
    Tip
    To find the custom field ID navigate to <JiraBaseURL>/secure/admin/ViewCustomFields.jspa and Edit the required field. The field ID is shown.
  6. Type an error message to show when the validator fails in Message to Show when Validation Fails.

This validator now ensures the custom field specified must have a value. If it is not, an error shows.

Sub-tasks Must be in Progress

As a project manager, you want to ensure all sub-tasks have been started before progress can start on the parent issue to keep issues aligned. Ensure all sub-tasks are In Progress before a parent issue can be transitioned to In Progress.

  1. Select the Start Progress transition.

  2. Click Validators→Add Validator.

  3. Select ScriptRunner Script and click Add.

  4. Add a description of the validator in Name of ScriptRunner Script Validator for example, All Sub-tasks Must be In Progress.

  5. Insert the following ScriptRunner Script Validator:

      issue.subtasks.filter(subtask => subtask.status.name == 'In Progress').length == issue.subtasks.length
  6. Type an error message to show when the validator fails in Message to Show when Validation Fails.

This validator now ensures all sub-tasks of a parent issue are in the In Progress workflow step before the parent issue can be transitioned to In Progress.

Issue Description Length

As a support manager, you want to ensure that all bugs reported have detailed descriptions so you can replicate and solve as easily as possible. Enforce thorough descriptions on all issues before they can be created by setting a minimum character length.

  1. Select the Open transition.

  2. Click Validators→Add Validator.

  3. Select ScriptRunner Script and click Add.

  4. Add a description of the validator in Name of ScriptRunner Script Validator for example, Description Length.

  5. Insert the following ScriptRunner Script Validator. Change length >30 to specify the minimum required characters:

      issue.description.plainText.length >30
  6. Type an error message to show when the validator fails in Message to Show when Validation Fails.

This validator shows an error and blocks the creation of an issue if the Description field is under 30 characters.

Issue Must be in Current Sprint

As a project manager, you want to ensure that only issues planned in the current sprint are worked on. Allow work to be started only on issues that are in the current active sprint.

  1. Select the Start Progress transition.

  2. Click Validators→Add Validator.

  3. Select ScriptRunner Script and click Add.

  4. Add a description of the validator in Name of ScriptRunner Script Validator for example, Enforce Current Sprint.

  5. Insert the following ScriptRunner Script Validator:

      issue.sprint.state == 'active'
  6. Type an error message to show when the validator fails in Message to Show when Validation Fails.

This validator shows an error message when a user tries to transition an issue outside of the current active sprint.