Listeners Tutorial

For a video on listeners, see the Using Listeners training video. 

While out-of-the-box, Jira includes tools to help with automating tasks, you may find yourself looking for more. Perhaps you use post functions to handle some automated events after a a user completes a workflow transition. Or maybe you use some automation rules in Jira Service Management to alert administrators to high-priority tickets. With ScriptRunner for Jira, there are several ways to turn a manual process into an automatic one. One of those ways is with a listener. A listener, also known as a script listener, is an automated procedure or function in ScriptRunner that waits (or listens) for a specific event to occur in Jira and then carries out an action if the event occurs.

Listeners are part of the overall ScriptRunner functionality, so you manage them from the Listeners page of ScriptRunner.

Image of listeners page

The basic thing to understand is that listeners just hang out in your Jira instance and wait for an event to happen in order to carry out an action. You have many possibilities for listener events, including things like logging work on an issue and reopening an issue. In these examples, either event could trigger an action as a result of the event. In addition to events, you can also apply conditions to a listener. So, maybe you don't want something to happen every time an issue is created, but you do need an email to send each time an issue is created from a certain high-priority project. You can set this up with a script listener and apply the appropriate conditions.

When a listener's event occurs, the listener then fires off the action you set up. ScriptRunner for Jira includes several built-in options for script listeners, or you can work with your own if you are feeling groovy (writing in Groovy, that is). So, if you want to create a sub-task if someone selects a certain value from a select list on an issue, you can do that with a listener.

Why use listeners?

Listeners allow you more control over automated actions than what you would find in a post-function. For example, let's say that whenever a Critical level priority issue occurs in a particular project, you need for a cloned issue to be created in a different project. You could use a workflow post-function to do this when a Critical level issue is being created, but if the issue is created as Major priority, then subsequently edited and changed to Critical, a workflow function would not catch it. A listener would though!

ScriptRunner enables you to create two types of listeners: built-in listeners and custom listeners.

Built-In listeners

Use the built-in listeners if you do not want to write Groovy scripts in order to create custom listeners. Be aware, however, that some of these built-in listeners require a little bit of scripting in the Condition inline field. There are several examples if you use a condition, but you may need to edit the script to match your exact project key. For example:

  • Send Custom Email (non-issue event)
  • Version Synchroniser

  • Add Current User as Watcher

  • Clone Issue and Links

  • Create Sub-task

  • Fast-track Transition an Issue

  • Fire Event When Condition is True

  • Post a Message to a Chat Service

  • Send Custom Email

You can write three types of custom listeners, but we don’t go into detail on that process here.

For examples of custom listeners, see the Adaptavist Library.

Parts of a listener


Each listener needs an event to trigger it’s action. A listener is essentially "listening" for this event to occur. Some examples of events:

  • A user comments on an issue

  • A watcher was added to an issue

  • An issue was closed

  • An issue was reopened.

Depending on the application installed, you may see different events for Jira Software and Jira Service Management.

Optional condition

If you choose, you can select a condition to apply to your listener. Conditions limit the events the listener looks for to just issues or events that match the conditions. Some examples of conditions:

  • A project matches a specific key

  • An issue has a certain priority, such as Major

  • A cascading select list has a certain first value.

    • You see these and other condition options when you choose to Show Examples under the Condition inline script editor. You can use additional conditions if you know what you are looking for by typing in the script editor.


This setup is similar to automation rules in Jira Service Management, with the condition action as your "If". You can select specific projects to associate a listener with, both using the Project Key menu, or using the condition: issue.projectObject.key == 'Project Key'

Some actions you can use:

  • Create a sub-task

  • Add current user as a watcher

  • Fire an additional event, such as "issue created"

  • Send a custom email.


Create a sub-task

In this example, create a listener that creates a sub-task based on a certain event and condition. For our example, we create a sub-task on high-priority issues in the Great Adventure Licensing and Financing project.

  1. From ScriptRunner, select the Listeners tab.
  2. On the Listeners page, select Create Listener.

  3. Select Create a sub-task.

  4. Complete the fields for your listener:

    1. Name: Enter a name for the listener. For our example, we are creating licensing sub-tasks when high-priority issues receive a comment in the licensing project.

    2. Applied to: Select the project(s) you want the listener to apply to. 

    3. Events: Select the events the listener will fire on. We are using Issue Commented.

    4. Condition: Enter a condition if you wish to use one. This condition will apply some limitations on the listener, defining, beyond project, when the listener should run. There is a list of examples under this field. For our example we are using priority and looking for issues that are high priority. The default example is Major, but you can update this with a different priority in the Condition inline script field.

    5. Other fields specific to the listener you chose. For example, we are using the Target Issue Type of Licensing for the new sub-task and leaving the summary blank to inherit the summary from the parent.

  5. Experiment with Sub-task Summary and Fields to Copy, if you wish. In our example, we have left these fields blank.

  6. Finally, if you want to add any additional actions or add a sub-task action, you can do that before adding your sub-task. For our example, we will set the sub-task status to To Do.

  7. When you are done with your script listener options, select Add. We recommend testing your script listener to make sure it is working properly. For our example, we added a comment to an issue in the affected project. As a result, we have a sub-task with a summary copied from the parent issue in the To Do status.

Add the current user as a watcher

This example creates a listener that adds the current user as a watcher. This listener may be useful if you want to stay updated on the progress of an issue after you complete an action on that issue, such as assigning the issue or leaving a comment. For our example, we add the current user as a watcher when they assign a Payroll type issue.

  1. From ScriptRunner, select the Listeners tab.
  2. On the Listeners page, select Create Listener.

  3. From the options, select Adds the current user as a watcher.

  4. Complete the fields for your listener:

    1. Name: Enter a name for the listener. 

    2. Applied to: Select the project(s) you want the listener to apply to. 

    3. Events: Select the events the listener will fire on. For our example, we will use the Issue Assigned event.

    4. Condition: Select any conditions you want to apply to the listener. For this particular listener, you may want to restrict to certain projects, priorities, or by certain selections within select lists. For our example, we are using the condition of Issue Type to look for only the Payroll issues.

Your results may vary depending on if you chose a different even or a different condition. You can test this listener by going to an issue and selecting an assignee, then noting the Watchers section of the page. Before trying this listener, make sure that you are not already watching the page.

For more examples of Listeners, visit our documentation.

On this page