The Adaptavist Group LogoDocumentation

Workflow Validators

Use workflow validators to enforce rules when a user attempts a transition.

Tip: Terminology updates

Atlassian has updated its workflow terminology as part of the new workflow editor experience. Some names and concepts may differ from what you're used to in the classic editor. For a detailed description of the changes, refer to Atlassian's official workflow documentation.

Supported spaces

Workflow rules are available in company-managed spaces only. Team-managed spaces are not currently supported.

ScriptRunner's workflow rules do not appear as options when you edit a team-managed workflow, so you cannot add them there.

Scripted workflow validators

In the Jira workflow editor, a scripted validator is the rule called Validate using a script (ScriptRunner). Your script returns whether the transition is allowed, along with an optional message explaining why it was blocked.

Scripted workflow validator reuse

You can create a scripted workflow validator once in ScriptRunner and reuse it across multiple workflows and transitions. This helps you:

  • Maintain common logic in a single place (for example, requiring a fix version or a comment).
  • Apply consistent validation rules across spaces and workflows.
Warning: When you edit a reused scripted workflow validator, the changes apply to all workflows and transitions that use that validator. Always plan and test changes in a non‑production environment before updating a reused validator.

Output and logging

When you run a script, the output panel shows:

  • Anything logged with console.log(...).
  • The final value returned by your script with return.
  • The error, if the script failed, with the full untrimmed error behind Full error.

Use console.log(...) for messages, intermediate values, or debugging. A validator returns an object with a result of true or false, and an optional errorMessage shown to the user when the transition is blocked.

Activity history

Saved workflow validators keep activity history, so you can review when they were run, and what the output was, making it easier to audit and troubleshoot. For how long activity is kept, see Run history retention.

Create a scripted workflow validator

Follow these steps to create a new scripted workflow validator in ScriptRunner:

  1. In Jira administration, select Marketplace apps.
  2. Under Apps, select ScriptRunner.
  3. Select Workflow validators.
  4. Select Create.
  5. Enter a Name and, optionally, a Description for your validator.
  6. Optionally, add Labels to group this validator with others.

    Start typing to reuse an existing label. Labels are saved in lowercase, with hyphens instead of spaces.

  7. Write your script in the editor.
    Tip: To help you write scripts, you can use the workflow validator scripted examples, use HAPI, or select Example scripts directly in the script editor. You can also use dynamic forms to add configurable input fields to your script, making it reusable across multiple workflow rules without any code changes.
  8. Choose who you want the script to Run as.

    Select whether the workflow validator runs with ScriptRunner app permissions or as a specific user.

  9. Optional: Select Test workflow validator to test your script against JSON data and make sure it works as expected (see Test a scripted workflow validator for more details).
    • You can load JSON data for a specific work item, choose which transition to test against, edit the data, and optionally save it for reuse in future tests of this workflow validator.
    • If the script performs updates (for example, creates or edits work items), those changes are applied to your Jira instance.
    • Test in a non‑production environment first.
    • Use the Output panel to review results and troubleshoot any errors.
  10. Select Publish.

Add your scripted workflow validator to a workflow transition

After you create a scripted workflow validator, attach it to a specific transition in a workflow:

  1. In Jira Work items settings, go to the Workflows menu.
  2. For your chosen workflow, open the Actions ellipsis (…) and select Edit.
  3. Select the transition you want to add your scripted workflow validator to.
    The Transition panel displays.
  4. Select the Add rule button.
  5. Find the Validate using a script (ScriptRunner) rule.
  6. In the rule configuration, choose your scripted workflow validator from the drop-down list.
  7. Select Add.
  8. Select Update workflow

Test a scripted workflow validator

You can test your scripted workflow validators against JSON data for work items before using them on real screens. This lets you confirm that your script behaves as expected for a specific work item. Test data is the JSON data that describes the work item and transition your scripted workflow validator runs against. For scripted workflow validators, the JSON data typically includes:

  • issue: the work item (for example, id, key)
  • modifiedFields: the fields that are changing as part of the transition (for example, assignee, status)
  • transition: basic details of the transition (for example, from and to status IDs)
  • user: the user attempting the transition (for example, accountId)
  • context: additional information about where and how the validator is running (for example, cloudId, moduleKey, and userAccess
  • contextToken: an identifier for the current validation context

The full test data is shown in the test panel so you can see exactly what data your workflow validator receives when the transition runs.

Test your workflow validator as follows:

  1. When creating or editing a workflow validator, select Test workflow validator.
    A testing panel displays.
  2. Enter a work item key (for example, ABC-123).
    Note: The work item must have already been through at least one transition for transitions to display in the dropdown. We recommend you enter a work item that has been through the transition you want to test this workflow validator against.
  3. Select a transition that the work item has previously gone through.
    This loads test data for that work item.
  4. Optional: Edit the test data if necessary.

    This is useful if you want to simulate a different transition, or change which fields are being modified, without performing a real transition on a work item.

  5. Select Run.

    The Output panel shows:

    • Anything logged with console.log(...)
    • The final value returned by your script with return
  6. If necessary, edit your script and test again until the output matches your expectations.
    Warning: If your script performs updates (for example, creates or edits work items, comments, or links), those changes are applied to your Jira instance even when running tests. Always test destructive or bulk‑update logic in a non‑production environment first.
  7. Optional: Save the test data.

    The saved test data can be reused for future tests of the same workflow validator, so you do not need to re‑enter or reconstruct it each time.

Edit a scripted workflow validator

Use these steps to modify an existing scripted workflow validator:

  1. In Jira administration, select Marketplace apps.
  2. Under Apps, select ScriptRunner.
  3. Select Workflow validators.
  4. Find your scripted workflow validator in the list and select Edit.
  5. Modify the validator as needed.

    Your changes are saved automatically as a draft. The published version keeps running until you publish again.

  6. Optional: Select Test workflow validator, then Run to run your script and make sure it works as expected.
    • If the script performs updates (for example, creates or edits work items), those changes are applied to your Jira instance.
    • Test in a non-production environment first.
    • Use the Output panel to review results and troubleshoot any errors.
  7. Select Publish changes.
Note: Any changes you publish here apply to all workflow transitions that use this validator.

Enable and disable your Scripted workflow validator

You can enable or disable scripted workflow validators:

  • Globally in ScriptRunner (affects all transitions that reference the validator).
  • Per transition in a specific workflow (affects only that transition).

Use global enable/disable when you want to stop a validator everywhere. Use transition‑level enable/disable when you only want to pause or remove it from a specific workflow path.

Enable or disable globally

To enable or disable a scripted workflow validator everywhere it is used:

  1. In Jira administration, select Marketplace apps.
  2. Under Apps, select ScriptRunner.
  3. In ScriptRunner, select Workflow validators.
  4. Locate the scripted workflow validator.
  5. Open the ellipsis (…) menu for that validator and select Disable or Enable.

    This setting applies to every workflow transition that references the validator. Disabling it here prevents the script from running anywhere, without needing to edit each workflow.

Enable or disable a specific transition

To enable or disable a scripted workflow validator on a single transition:

  1. In Jira Work items settings, go to the Workflows menu.
  2. For your chosen workflow, open the Actions ellipsis (…) and select Edit.
  3. Select the transition with your scripted workflow validator.
    The Transition panel displays.
  4. In the Rules list, locate the Validate using a script (ScriptRunner) rule that uses your validator.
  5. Check or uncheck Disable this script from running in this rule.
  6. Select Update to save the rule change.
  7. Select Update workflow

Delete a scripted workflow validator

Remove scripted workflow validators you no longer need to keep your list organized and reduce clutter. When you delete a scripted workflow validator, it's removed from your active Workflow validators list and is no longer available on workflow transitions. Any workflows and transitions that referenced the validator may still run, but the deleted script will no longer run as part of those transitions.

Tip: Before you delete a scripted workflow validator, check which workflows it's used in. Open the validator you want to delete, and review the Used in workflows list so you understand which workflows and transitions will be affected before you remove it.

To delete a scripted workflow validator:

  1. In Jira administration, select Marketplace apps.
  2. Under Apps, select ScriptRunner.
  3. Select Workflow validators.
  4. Find the scripted workflow validator you want to remove.
  5. Open the ellipsis (…) menu for that validator.
  6. Select Delete.
  7. When prompted, confirm that you want to delete the scripted workflow validator.
    Note: Deleted scripted workflow validators can be restored, including their activity history.

Restore a deleted scripted workflow validator

When you restore a scripted workflow validator, it becomes available again in ScriptRunner and is reconnected to any active workflows and transitions that previously used it. Those transitions will start running the validator script again the next time they are executed, and the validator's activity history remains available.

To restore a deleted scripted workflow validator:

  1. In Jira administration, select Marketplace apps.
  2. Under Apps, select ScriptRunner.
  3. Select Workflow validators.
  4. Use the filter and select Deleted to view deleted scripted workflow validators.
  5. Find the scripted workflow validator you want to restore.
  6. Open the ellipsis (…) menu for that validator.
  7. Select Restore.

Expression-based workflow validators

Use expression-based workflow validators to check a work item when a user attempts a transition. You write a Jira expression that must be true for the transition to go ahead, so you can require field values or enforce business rules without writing a full script. In the Jira workflow editor the rule is called Validate using a Jira expression (ScriptRunner).

What you configure

An expression-based validator has two settings, both required:

  • Jira expression: an expression that evaluates to true or false. If it is false, the transition is blocked.
  • Error message: the message shown to the user when the validation fails. Write it to say what they need to change, because this is all they see.

Preview before you save

You can check your expression against a real work item before saving the rule. Expand the preview section, enter a work item key, and ScriptRunner evaluates your expression against that work item and shows the result.

This is worth doing for every validator. An expression that fails to evaluate, or that is true when you expected false, is much easier to spot here than after someone is blocked by it.

Create an expression-based workflow validator

You can also validate transitions using Jira expressions instead of scripts:

  1. In Jira Work items settings, go to the Workflows menu.
  2. For your chosen workflow, open the Actions ellipsis (…) and select Edit.
  3. Select the transition you want to add your workflow validator to.
    The Transition panel displays.
  4. Under Validate details, select Add validate details rule.
  5. Find and select Validate using a Jira expression (ScriptRunner).
  6. Enter a Jira expression that must evaluate to true for the transition to succeed.
    Tip: You can start from the workflow validator expression examples provided.
  7. Enter an Error message.

    This is the message users see when their transition attempt fails validation.

  8. Optional: Use the test area to test your expression against a Jira work item.
  9. Select Add.
  10. Select Update workflow to publish your changes.

Edit an expression-based workflow validator

Use these steps to modify an existing expression‑based workflow validator:

  1. In Jira Work items settings, go to the Workflows menu.
  2. For your chosen workflow, open the Actions ellipsis (…) and select Edit.
  3. Select the transition with your workflow validator.
    The Transition panel displays.
  4. In the Rules list, locate the Validate using a Jira expression (ScriptRunner) rule.
  5. Modify the Jira expression or the Error message as needed.
  6. Optional: Use the test area to test your expression against a Jira work item.
  7. Select Update to save the rule change.
  8. Select Update workflow to publish your changes.

Delete an expression-based workflow validator

To remove an expression-based workflow validator from a transition:

Warning: Deleting an expression-based workflow validator is permanent. Once you remove it from a transition, you cannot recover or restore it later. If you need the same validator again, you will have to recreate it.
  1. In Jira Work items settings, go to the Workflows menu.
  2. For your chosen workflow, open the Actions ellipsis (…) and select Edit.
  3. Select the transition that contains your expression-based validator.
    The Transition panel displays.
  4. In the Rules list, select the Validate using a Jira expression (ScriptRunner) rule you want to delete.
  5. Open the ellipsis (…) menu and select Delete rule.
  6. Select Update workflow to publish your changes.

Search documentation

Start typing to search the docs.