Workflow Actions

Learn how to create, test, attach, and manage scripted workflow actions that run when a work item transitions to a new status.

With ScriptRunner, you can automatically update fields, create or link related work items, or send notifications as part of the transition. This helps you enforce business rules, reduce manual steps, and maintain workflow consistency.

Note: When your script runs

Workflow actions run as part of a work item transition, so there can be a short delay between the transition happening and your script running. For more information, see Performance and latency on the Scripting limitations page.

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.

Scripted workflow action reuse

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

Maintain common logic in a single place (for example, notifications, task creation, field synchronization).
Apply consistent behavior across spaces and workflows.

Warning: When you edit a scripted workflow action that is reused, the changes apply to all workflows and transitions that use that action. Always plan and test changes in a non‑production environment before updating a reused action.

Output and logging

When you test 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, and include a return statement for the main result you want to display.

Activity history

Saved workflow actions 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.

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.

Create a scripted workflow action

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

In Jira administration, select Marketplace apps.
Under Apps, select ScriptRunner.
Select Workflow actions.
Select Create.
Enter a Name and, optionally, a Description for your action.
Optionally, add Labels to group this action with others.
Start typing to reuse an existing label. Labels are saved in lowercase, with hyphens instead of spaces.
Write your script in the editor.
Tip: To help you write scripts, you can use the workflow action examples, use HAPI, or select Example scripts directly in the script editor. You can also use parameters (dynamic forms) to add configurable input fields to your script, making it reusable across multiple workflow rules without any code changes.
Choose who you want the script to Run as. Select whether the workflow action runs with ScriptRunner app permissions or as a specific user.
Optional: Select Test workflow action to test your script against JSON data and make sure it works as expected (see Test a scripted workflow action for more details).
- You can load JSON data for a specific work item, choose which of its transitions to test against, edit the data, 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.
Select Publish.

Add your scripted workflow action to a workflow transition

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

In Jira Work items settings, go to the Workflows menu.
For your chosen workflow, open the Actions ellipsis (…) and select Edit.
Select the transition you want to add your scripted workflow action to.
The Transition panel displays.
Under Perform actions, select Add perform actions rule.
Find and select the Perform an action using a script (ScriptRunner) rule.
In the rule configuration, choose your scripted workflow action from the drop-down list.
Select Add.
Select Update workflow to publish your changes.

Test a scripted workflow action

You can test your scripted workflow actions 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 action runs against. For scripted workflow actions, the JSON data typically includes:

issue: the work item and its core fields (for example, id, key, fields.summary, fields.status, fields.priority, fields.assignee, and so on).
transition: details of the workflow transition (for example, id, name, from, to, and an executionId).
changelog: information about what changed during the transition (for example, fields that were updated).
atlassianId: the ID of the user who triggered the transition.
context: additional information about where and how the action is running (for example, cloudId, moduleKey, and userAccess flags).

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

Test your workflow action as follows:

When creating or editing a workflow action, select Test workflow action.
A testing panel displays.
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 action against.
Select a transition that the work item has previously gone through.
This loads test data for that work item.
Optional: Edit the test data if necessary.
This is useful if you want to simulate a different transition, or change what the changelog says was updated, without performing a real transition on a work item.
Select Run.
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.
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.
Optional: Save the test data.
The saved test data can be reused for future tests of the same workflow action, so you do not need to re‑enter or reconstruct it each time.

Edit a scripted workflow action

Use these steps to modify an existing scripted workflow action:

In Jira administration, select Marketplace apps.
Under Apps, select ScriptRunner.
Select Workflow actions.
Find your scripted workflow action in the list and select Edit.
Modify the action as needed.
Your changes are saved automatically as a draft. The published version keeps running until you publish again.
Optional: Select Test workflow action, 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.
Select Publish changes.

Note: Any changes you publish here apply immediately to all workflow transitions that use this action.

Enable and disable a scripted workflow action

You can enable or disable scripted workflow actions:

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

Use global enable/disable to stop an action 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 action everywhere it is used:

In Jira administration, select Marketplace apps.
Under Apps, select ScriptRunner.
In ScriptRunner, select Workflow actions.
Locate the scripted workflow action.
Open the ellipsis (…) menu for that action and select Disable or Enable.

This setting applies to every workflow transition that references the action. 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 action on a single transition:

In Jira Work items settings, go to the Workflows menu.
For your chosen workflow, open the Actions ellipsis (…) and select Edit.
Select the transition with your scripted workflow action.
The Transition panel displays.
In the Rules list, locate the Perform an action using a script (ScriptRunner) rule that uses your action.
Check or uncheck Disable this script from running in this rule.
Select Update to save the rule change.
Select Update workflow to publish your changes.

Delete a scripted workflow action

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

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

To delete a scripted workflow action:

In Jira administration, select Marketplace apps.
Under Apps, select ScriptRunner.
Select Workflow actions.
Find the scripted workflow action you want to remove.
Open the ellipsis (…) menu for that action.
Select Delete.
When prompted, confirm that you want to delete the scripted workflow action.

Note: Deleted scripted workflow actions can be restored, including their sctivity history.

Restore a deleted scripted workflow action

When you restore a scripted workflow action, 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 script again the next time they are executed, and the action's activity history remains available.

To restore a deleted scripted workflow action:

In Jira administration, select Marketplace apps.
Under Apps, select ScriptRunner.
Select Workflow actions.
Use the filter and select Deleted to view deleted scripted workflow actions.
Find the scripted workflow action you want to restore.
Open the ellipsis (…) menu for that action.
Select Restore.