Workflow Validators

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

• Use expression-based validators to ensure a rule is met at transition time without writing a full script.

• Use scripted validators to implement complex checks that depend on multiple fields or related work items.

Scripted workflow validators

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.

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

Use console.log(...) for messages, intermediate values, or debugging, and include a return statement for the main result you want to display. When testing, each time you select Run, the output panel is cleared and refreshed with the latest logs and return value.

Execution history

Saved workflow validators keep a full execution history (under Output), so you can review when they were run, and what the output was, making it easier to audit and troubleshoot.

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.js.
3. Select Workflow validators.
4. Select Create.
5. Enter a Name and, optionally, a Description for your validator.
6. Choose who you want the script to Run as. Select whether the workflow validator runs with ScriptRunner app permissions or as a specific user.
7. Write your script in the editor.
   

   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. Optional: Select Test 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 a JSON data for a specific work item, edit it, and optionally save it for reuse in future tests of this workflow action.
   • 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.
9. Select Save.

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 to publish your changes.

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 a workflow validator, select Test. A testing panel displays. 

2. Enter a work item key (for example, ABC-123).

   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 running the script against a different work item ID or context without changing your actual configuration.

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.

   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.js.
3. Select Workflow validators.
4. Find your scripted workflow validator in the list and select Edit.
5. Modify the validator as needed.
6. Optional: Select 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 Save.
   

   Any changes you save here apply immediately 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.js.
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 to publish your changes.

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.

To delete a scripted workflow validator:

1. In Jira administration, select Marketplace apps.
2. Under Apps, select ScriptRunner.js.
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.
   

   Deleted scripted workflow validators can be restored, including their execution 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 execution history remains available.

To restore a deleted scripted workflow validator:

1. In Jira administration, select Marketplace apps.
2. Under Apps, select ScriptRunner.js.
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

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.
   

   To help you write an expression, you can use the AI Assistant in the rule configuration. Keep your prompt specific and include a real work item key for the AI to test against. You can also start from the 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:

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.