Event Listener Expression Examples

An event listener's expression filter is a Jira expression that runs before your script. If it returns true, your script runs for that event; if false, the event is skipped. The expression works with a single variable, event, which holds the event payload (the same object your script receives). Read its properties to build your condition, and combine conditions with the operators && (and), || (or), and ! (not).

Tip: Atlassian has introduced updated terminology for issues (now referred to as work items) and projects (now referred to as spaces). In this documentation, a work item corresponds to a Jira issue (Task, Bug, Story, Sub-task, etc.), and a space is equivalent to a Jira project.

In Jira expressions, code, and the Jira APIs, you will still see the original terms issue and project, for example, in event.issue and event.issue.fields.project. When you read an expression or code, treat an issue as a work item and a project as a space.

Two things to keep in mind:

You can only filter on data that's in the event payload. Work item events include event.issue.fields (summary, work item type, space, status, priority, labels, components, assignee, reporter) and, for updates, event.changelog. Data that isn't in the payload (such as a user's groups or roles, or a work item's links or attachments) can't be filtered here; do those checks in your script.
Test the expression before relying on it. If a filter errors, the event is still delivered and your script runs. So a broken filter quietly stops filtering instead of failing.

Filter by space

Execute the event listener only for work items in a specific space:

event.issue.fields.project.key == 'DEMO'
 
// Multiple spaces
['DEMO', 'TEST', 'PROD'].includes(event.issue.fields.project.key)

Filter by work item type

Execute the event listener only for specific work item types:

event.issue.fields.issuetype.name == 'Bug'
 
// Multiple types
['Bug', 'Task', 'Story'].includes(event.issue.fields.issuetype.name)
 
// Exclude subtasks
!event.issue.fields.issuetype.subtask

Filter by priority

Execute the event listener only for high-priority work items. Priority is an optional field, so use ?. to keep the expression safe when it is not set:

event.issue.fields.priority?.name == 'High'

Filter by status

Execute the event listener only when a work item is in a specific status:

event.issue.fields.status.name == 'In Progress'

Filter by assignee

Execute the event listener based on who the work item is assigned to:

// Specific person
event.issue.fields.assignee?.accountId == '5cf7c174eba28b4ea84a7cb5'
 
// Assigned to anyone / unassigned
event.issue.fields.assignee != null
event.issue.fields.assignee == null

Filter by reporter

Execute the event listener only for work items reported by a specific user. The payload identifies users by accountId only, so to filter by a reporter's group, do that check in your script:

event.issue.fields.reporter.accountId == '5cf7c174eba28b4ea84a7cb5'

Filter by labels

Execute the event listener only when a work item has a specific label:

event.issue.fields.labels != null && event.issue.fields.labels.includes('urgent')
 
// Any of several labels
event.issue.fields.labels != null && event.issue.fields.labels.some(label => ['urgent', 'critical', 'hotfix'].includes(label))

Filter by components

Execute the event listener only when a work item has a specific component:

// Has a specific component
event.issue.fields.components != null && event.issue.fields.components.some(c => c.name == 'Backend')
 
// Has at least one component
event.issue.fields.components != null && event.issue.fields.components.length > 0

Filter by field changed

Execute the event listener only when a specific field has changed. This is available on updated and assigned events only; use fieldId for system fields ( field holds the display name):

event.changelog.items.some(i => i.fieldId == 'priority')
 
// Assignee changed
event.changelog.items.some(i => i.fieldId == 'assignee')

Combine multiple filters

Combine several conditions to target exactly the events you want:

event.issue.fields.project.key == 'DEMO'
  && event.issue.fields.priority?.name == 'High'
  && !event.issue.fields.issuetype.subtask

Some conditions can't go in the filter: check them in your script instead

An event listener has two stages: the filter (this expression, which decides whether your script runs) and the script (which runs if the filter passes). The filter can only see what's in the event payload, and a few things you might want to filter on aren't included, so the expression can't check them:

Whether a user is in a group or space role (the payload gives only a user's accountId)
The work item's linked work items
The work item's attachments
Description or custom-field text

You can still act on these, just move the check into your script. Leave the filter blank (or broad), then at the top of your script fetch the extra data with Issues.getByKey(event.issue.key, …) (or the users/groups APIs) and return early when the condition isn't met:

export default async function (event) {
 // Fetch the data the event doesn't include
 const issue = await Issues.getByKey(event.issue.key, { fields: ['...'] })
 
 // Stop here if your condition isn't met
 if (/* condition not met */) return
 
 // ...otherwise, carry on
}