Event Listeners

Use Event listeners to create automated procedures that listen for a specific event to occur in Jira and then run a script when it does. You can use event listeners to:

• Automate work item updates based on field changes

• Post a message to Slack when a work item is created

• Create a sub-task when a specific work item type is created

Available events

This feature provides access to various events:

• Attachment events

• Board events

• Comment events

• Component events

• Configuration events

• Context events

• Expression events

• Field events

• Work item events

• Work item link events

• Work item property events

• Work type events

• Project (space) events

• Sprint events

• Time Tracking provided changed event

• User events

• Version events

• Worklog events

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 event listeners 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.

Event listeners versus workflow actions (formerly post functions)

The crucial difference between event listeners and workflow actions (formerly post functions) is that the former rely on an event occurring at any time, whereas the latter rely on a transition change. Event listeners give you more control over automated actions than you would get with a workflow action.

For example, whenever there is a Critical-priority work item in a given space, you want a message sent to a Slack channel. If you use a workflow action to do this, an event fires only after a transition, not if the work item is edited. Therefore, if the work item's priority is set to Critical, the workflow action does not catch it until after the work item has been transitioned. To achieve this use case, you would use an event listener to catch the change in priority when it happens.

How event filtering works

Every event listener has a filtering mode that decides whether the listener runs for every selected event, or only for events that meet extra conditions. There are three modes:

You must select at least one event before you can choose Basic filter or Jira expression.

What the Basic filter can filter on

The Basic filter provides up to three options:

• Space category
• Space
• Work type 

Which options appear depends on the events you selected. Some events display all three options, while others show only one or two. For example, events that involve a work item can offer all three options, whereas space-level events provide only Space category and Space.

If the selected events do not support any of these options (for example, user or board events), the Basic filter is not available. In that case, you are directed to use a Jira expression instead.

Switching between a Basic filter and a Jira expression

You can switch between Basic and Jira expression modes without losing work. Each mode keeps its own filter, and switching modes does not clear your Basic filter selections.

Basic filter to a Jira expression: Your dropdown selections are converted into an equivalent Jira expression, which you can then edit. Because edited expressions cannot be reliably turned back into dropdowns, you are asked to confirm before switching.

Jira expression to a Basic filter:

• If the expression is auto-generated and unedited, you can switch back and forth freely.
• If you edited the expression, switching back to Basic does not change your dropdowns; your edits remain only in Jira expression mode.
• If a listener was saved with a handwritten expression, the Basic filter is no longer available for that listener.

How filtering is applied

Whatever mode you choose, filtering is ultimately applied as a Jira expression that is evaluated when an event occurs. If a filter expression cannot be evaluated for an event, the event is still delivered, and your script runs, so a filter that fails to evaluate stops filtering rather than blocking events. For examples of the variables and syntax you can use in a Jira expression, see Event listener expression examples.

Create an event listener

To create an event listener, proceed as follows:

1. In Jira administration, select Marketplace apps.
2. Under Apps, select ScriptRunner.js.
3. Select Event listeners.
4. Select Create.
5. Enter a Name and, optionally, a Description.
6. Choose the Event(s) you want your script to run on.
7. Choose a filtering mode: No filter, Basic filter, or Jira expression. See How event filtering works for what each mode does and how to switch between them.
8. Write your script.
   

   To help you write scripts, you can use the event listener examples, use HAPI, or select Example scripts directly in the script editor.

9. Choose who you want the script to Run as. Select whether the event listener runs with ScriptRunner app permissions or as a specific user.
10. Optional: Select Test to test your script against JSON data and make sure it works as expected (see Test an event listener for more details).
    
    • You can load JSON data for a specific work item, edit it, and optionally save it for reuse in future tests of this event listener.
    • 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.
11. Select Save. 

Test an event listener

You can test your event listeners against test data before relying on them in production. This helps you confirm that your script behaves as expected for a specific work item and event. Test data is the JSON data that describes the work item and event your event listener runs against. For work item–related events, 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).
• eventType: the type of event that occurred (for example, a work item created or updated event).
• user: the user who triggered the event.
• Other event‑specific details, depending on the event you selected.

Test your event listener as follows:

1. When creating an event listener, select Test. A testing panel displays.
2. If the Enter a work item key field displays, enter a work item key (for example, ABC-123) to load event JSON data for that work item.
   

   When does the Enter a work item key field appear?

   The Enter a work item key field appears only when you select a single work item event of one of these types: created, deleted, viewed, or commented. For any other event (including other work item events such as updated or assigned, and non–work-item events such as board or sprint events), the field does not appear and you enter the JSON directly.

3. If no data is pre-loaded, enter your JSON data manually into the test panel. The eventType is automatically populated in the test data based on the event you selected.

4. Optional: Edit the test data if necessary. This is useful if you want to simulate different field values, event types, or users without changing real work items.
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 event listener, so you do not need to re‑enter or reconstruct it each time.

Edit an event listener

To edit an event listener, proceed as follows:

1. In Jira administration, select Marketplace apps.
2. Under Apps, select ScriptRunner.js.
3. Select Event listeners.
4. Find your event listener in the list and select Edit.
5. Modify the event listener as needed.
6. Optional: Select Test to test your script against JSON data and make sure it works as expected (see Test an event listener for more details).
   
   • You can load test data for a specific work item, edit it, and optionally save it for reuse in future tests of this event listener.
   • 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.

Enable and disable an event listener

To enable or disable your event listener:

1. In Jira administration, select Marketplace apps.
2. Under Apps, select ScriptRunner.js.
3. In ScriptRunner, select Event listeners.
4. Locate the event listener you want to enable or disable.
5. Open the ellipsis (…) menu for that event listener and select Disable or Enable.

Delete an event listener

Remove event listeners you no longer need to keep your list organized and reduce clutter. When you delete an event listener, it’s removed from your active event listeners list and will no longer run, but it isn’t permanently removed. You can still access and restore it from ScriptRunner if needed.

To delete an event listener:

1. In Jira administration, select Marketplace apps.
2. Under Apps, select ScriptRunner.js.
3. Select Event listeners.
4. Find the event listener you want to remove.
5. Open the ellipsis (…) menu for that event listener.
6. Select Delete.
7. When prompted, confirm that you want to delete the event listener.
   

   Deleted event listeners can be restored, including their execution history.

Restore a deleted event listener

You can restore deleted event listeners along with their execution history. To restore a deleted event listener:

1. In Jira administration, select Marketplace apps.
2. Under Apps, select ScriptRunner.js.
3. Select Event listeners.
4. Use the filter and select Deleted to view deleted event listeners.
5. Find the event listener you want to restore.
6. Open the ellipsis (…) menu for that event listener.
7. Select Restore. The event listener and its full execution history will be available again in your active Event listeners list.