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 returns | What happens |
|---|---|
true | The transition goes ahead. |
false | The transition is blocked. Jira shows its own message: The transition was rejected by validator "Scripted Validator". |
| A string | The transition is blocked, and Jira shows the string as the error message. |
| Anything else, or the expression fails | The 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β
| Variable | What it holds |
|---|---|
user | The person making the transition |
issue | The work item, including changes made on the transition screen |
originalIssue | The work item before those changes. Not available on the transition that creates the work item. |
project | The space of the work item |
transition | The transition being made |
workflow | The workflow that holds the validator |
config | The rule's saved configuration |
customerRequest, serviceDesk | The 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;
}
Relatedβ
- Add a validator: put a validator on a transition.
- Test a rule on a work item: see the message a person would get, before you save.
- Workflow conditions: hide a transition instead of blocking it.