Event Listeners

Learn how to create, filter, test, and manage event listeners that run a script automatically when specific events occur in Jira.

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.

Note: When your script runs

Event listeners run when a matching Jira event occurs, so there can be a short delay between the event happening and your script running. For more information, see Performance and latency on the Scripting limitations page.

Available events

An event listener can run on any of these events:

Attachment created (avi:jira:created:attachment)
Attachment deleted (avi:jira:deleted:attachment)
Board configuration-changed (avi:jira-software:configuration-changed:board)
Board created (avi:jira-software:created:board)
Board deleted (avi:jira-software:deleted:board)
Board updated (avi:jira-software:updated:board)
Comment deleted (avi:jira:deleted:comment)
Comment mentioned (avi:jira:mentioned:comment)
Component created (avi:jira:created:component)
Component deleted (avi:jira:deleted:component)
Component updated (avi:jira:updated:component)
Configuration changed (avi:jira:changed:configuration)
Expression failed (avi:jira:failed:expression)
Field context configuration updated (avi:jira:updated:field:context:configuration)
Field context created (avi:jira:created:field:context)
Field context deleted (avi:jira:deleted:field:context)
Field context updated (avi:jira:updated:field:context)
Field created (avi:jira:created:field)
Field deleted (avi:jira:deleted:field)
Field restored (avi:jira:restored:field)
Field trashed (avi:jira:trashed:field)
Field updated (avi:jira:updated:field)
Filter created (avi:jira:created:filter)
Filter deleted (avi:jira:deleted:filter)
Filter updated (avi:jira:updated:filter)
Space archived (avi:jira:archived:project)
Space created (avi:jira:created:project)
Space deleted (avi:jira:deleted:project)
Space restored (avi:jira:restored:project)
Space softdeleted (avi:jira:softdeleted:project)
Space unarchived (avi:jira:unarchived:project)
Space updated (avi:jira:updated:project)
Sprint closed (avi:jira-software:closed:sprint)
Sprint created (avi:jira-software:created:sprint)
Sprint deleted (avi:jira-software:deleted:sprint)
Sprint started (avi:jira-software:started:sprint)
Sprint updated (avi:jira-software:updated:sprint)
Timetracking provider changed (avi:jira:timetracking:provider:changed)
User created (avi:jira:created:user)
User deleted (avi:jira:deleted:user)
User updated (avi:jira:updated:user)
Version archived (avi:jira:archived:version)
Version created (avi:jira:created:version)
Version deleted (avi:jira:deleted:version)
Version merged (avi:jira:merged:version)
Version moved (avi:jira:moved:version)
Version released (avi:jira:released:version)
Version unarchived (avi:jira:unarchived:version)
Version unreleased (avi:jira:unreleased:version)
Version updated (avi:jira:updated:version)
Work item assigned (avi:jira:assigned:issue)
Work item commented (avi:jira:commented:issue)
Work item created (avi:jira:created:issue)
Work item deleted (avi:jira:deleted:issue)
Work item link created (avi:jira:created:issuelink)
Work item link deleted (avi:jira:deleted:issuelink)
Work item mentioned (avi:jira:mentioned:issue)
Work item property deleted (avi:jira:deleted:issue-property)
Work item property set (avi:jira:set:issue-property)
Work item updated (avi:jira:updated:issue)
Work item viewed (avi:jira:viewed:issue)
Work type created (avi:jira:created:issuetype)
Work type deleted (avi:jira:deleted:issuetype)
Work type updated (avi:jira:updated:issuetype)
Worklog created (avi:jira:created:worklog)
Worklog deleted (avi:jira:deleted:worklog)
Worklog updated (avi:jira:updated:worklog)

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

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:


Mode	What it does
No filter	The listener runs for all selected events, with no extra conditions. Use this when you want to react to every occurrence of the events you selected.
Basic filter	The listener runs only when your dropdown selections match. You build the conditions with dropdowns, so no scripting is required. Available only for event types that support structured filtering.
Jira expression	The listener runs only when a Jira expression you write returns `true`. Use this for conditions the Basic filter cannot express, or when your selected events are not compatible with the Basic filter.

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. You are asked to confirm first, because an edited expression cannot be reliably turned back into dropdowns.

Jira expression to a Basic filter: You are asked to confirm, because your expression cannot be turned into Basic filter settings. This includes an expression you wrote yourself without ever using the Basic filter. Any Basic filter selections you made earlier are still there, and your expression stays under the Jira expression option for as long as you stay on the page.

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:

In Jira administration, select Marketplace apps.
Under Apps, select ScriptRunner.
Select Event listeners.
Select Create.
Enter a Name and, optionally, a Description.
Optionally, add Labels to group this listener with others.
Start typing to reuse an existing label. Labels are saved in lowercase, with hyphens instead of spaces.
Choose the Event(s) you want your script to run on.
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.
Write your script.
Tip: To help you write scripts, you can use the event listener examples, use HAPI, or select Example scripts directly in the script editor.
Choose who you want the script to Run as. Select whether the event listener runs with ScriptRunner app permissions or as a specific user.
Optional: Select Test event listener 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.
Select Publish.

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.
comment: for comment events only, the work item's most recent comment.

Test your event listener as follows:

When creating or editing an event listener, select Test event listener.
A testing panel displays.
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.
Note: 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.
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.
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.
Select Run.
The Output panel shows:
- Anything logged with console.log(...)
- The final value returned by your script with return
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 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:

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

Enable and disable an event listener

To enable or disable your event listener:

In Jira administration, select Marketplace apps.
Under Apps, select ScriptRunner.
In ScriptRunner, select Event listeners.
Locate the event listener you want to enable or disable.
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:

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

Note: Deleted event listeners can be restored, including their activity history.

Restore a deleted event listener

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

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