Skip to main content

Workflow validators

A Scripted Validator checks a work item when someone confirms a transition, after the transition screen, and blocks the move when the check fails. It can tell the person what to fix, for example "Assign DEMO-12 before moving it."

Applies to: Script Master for Jira Β· Cloud, company-managed and team-managed spaces

A validator is a Jira expression that Jira evaluates. You can build it from checks without writing code, or write the expression yourself. Jira runs it, so a validator works without the Companion App.

Return a custom error message​

What the expression returns decides what happens to the transition.

The expression returnsWhat happens
trueThe transition goes ahead.
falseThe transition is blocked. Jira shows its own message: The transition was rejected by validator "Scripted Validator".
A stringThe transition is blocked, and Jira shows the string as the error message.
Anything else, or the expression failsThe transition is blocked, and Jira shows an evaluation failure that names the rule instead of your message.

To tell people what to fix, return a string:

issue.assignee != null
? true
: `Assign ${issue.key} before moving it.`

A throw counts as a failure. Throwing 'Assign the work item first.' shows this, not your text alone:

We failed to evaluate validator "Scripted Validator" for this issue transition. Expression threw an error: Assign the work item first.

The rule builder writes the message for you. See Message when it blocks.

Variables in a validator​

VariableWhat it holds
userThe person making the transition
issueThe work item, including changes made on the transition screen
originalIssueThe work item before those changes. Not available on the transition that creates the work item.
projectThe space of the work item
transitionThe transition being made
workflowThe workflow that holds the validator
configThe rule's saved configuration
customerRequest, serviceDeskThe request and its service desk, on Jira Service Management transitions only

To check what someone changed on the transition screen, compare issue with originalIssue, for example issue.summary != originalIssue.summary.

When a validator fails to evaluate​

If Jira can't evaluate the expression, the transition is blocked and the person sees the evaluation failure. Script Master counts these failures in the Last 7 days column of the Workflows tab.

Examples​

All three examples are also in the editor's Snippets.

Allowed work types​

The transition is allowed only for the listed work types.

['Bug', 'Task'].includes(issue.issueType.name)

Comment from the person moving it​

The transition is allowed only when the person moving the work item has commented on it.

issue.comments
.filter(c => c.author.accountId == user.accountId)
.length > 0

A message per missing value​

The transition is blocked with a different message for each missing value. The final else is required.

if (issue.assignee == null) {
return 'Assign the work item before moving it.';
} else if (issue.description == null) {
return 'Add a description before moving this work item.';
} else {
return true;
}