Listeners Tutorial

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 Script Listeners page of the Jira Administration menu (Administration>Manage Apps>Script Listeners).

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 the appropriate conditions applied.

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. If you use a condition, there are several examples, 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.

Parts of a Listener

Event

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.

Action

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.

Examples of Listeners

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 the Jira Administration menu, select Manage Apps.

2. On the Manage Apps page, under ScriptRunner, click Script Listeners.

3. On the Script Listeners page, click Create Listener.

4. Click your selection. The appropriate fields for that selection open for you to complete. For our example, we clicked Create a Sub-Task.

5. Complete the fields for your listener:

   1. Note: Put in an explanation of what this listener is intended to do for anyone who comes across it. For our example, we are creating a licensing sub-tasks when high-priority issues receive a comment in the licensing project.

   2. Project Key: Select the project(s) you want the listener paying attention to. Our key is GALM for this example. You don't have to remember the project key for this option, as you can select it from a list.

   3. Events: Click in the box for a list of events (there are many.) We are using Issue Commented.

      

   4. Condition: Select 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.

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

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

8. When you are done with your script listener options, click 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 the Jira Administration menu, select Manage Apps.

2. On the Manage Apps page, under ScriptRunner, click Script Listeners.

3. On the Script Listeners page, click Create Listener.

4. From the options, select Adds the Current User as a Watcher.

   

5. Select the appropriate project.

6. Select the Event(s) you want the listener to fire on. For our example, we are still in the Virtual Tours project and will use the Issue Assigned event.

7. Lastly, 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.