Script Listeners

What are Script Listeners?

A 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 sit on your instance and wait for a webhook event to happen before executing the listener script. Webhooks are fired after an action has taken place in Jira, such as when a project is created or if an issue is updated.

How to use Script Listeners

You may want to use a Script Listener to:

• Populate a project with initial issues when it is created.

• Post a message to Slack when an issue is created.
• Store story points of sub tasks against the parent issue.

Script Listeners and Post Functions

The crucial difference between Script Listeners and Post Functions is that the latter relies on a transition change, whereas the former relies on an event occurring, which could happen at any time.

Script Listeners give you more control over automated actions than you would get with a Post Function.

For example, whenever there is a Critical level priority issue in a certain project, you want a message to be sent to a Slack channel. If you use a post function to do this, an event would fire only after a transition, not if the issue is edited. Therefore, if the priority of the issue was edited to Critical the post function would not catch it until after the issue had been transitioned. To achieve this use case, you would use a listener to catch a change in priority when it happened. 

Before you start

Create a Script Listener

1. Navigate to ScriptRunner → Script Listeners.
   Upon opening the Script Listeners page, you are presented with either a list of previously created script listeners, or if you have not previously created any, you will see a landing screen.
   1. Click Create Script Listener from the previously created list. You can also choose to Edit or Delete your selected script listener via the Actions ellipsis on this page.
      
      OR
   2. Click Create Script Listener from the initial landing screen if none have been previously created.
      
      OR
   3. Click Add Examples from the initial landing screen to add two script listener examples to your instance. From here, you can select your preferred example and either Edit or Delete it via the Actions ellipsis.
2. Enter a name for the listener in Script Listener Called.
   

3. Select the event(s) you wish the listener script to trigger on in On These Events, for example, Issue Updated.

4. Select the projects you want the listener to be active for; you can select All Projects (default) or a number of individually selected projects per listener.

   Project settings only apply to issue, project, issuelink (source issue), version, and comment related events. If you require filtering on issuelinks for both source and destination issue, you should add both projects to the filter

5. Choose from either ScriptRunner Add-On User or Current User as the user you wish to run the listener for in As This User. Script Listeners can make requests to Jira using either user.
   

   When using the Initiating User, any action occurring as a result of the function is registered as being performed by them. For example, if an issue is commented on, the comment comes from the Initiating User rather than the ScriptRunner Add-on User who may have nothing to do with the issue/project affected. Permissions are considered when executing actions. The user selected in the Run as User field must have the correct permissions to do the action specified. Typically the ScriptRunner Add-on User has project admin permissions; however, this can be restricted. The Initiating User may have higher permissions than the ScriptRunner Add-on User.

6. Enter a condition on which the code will run.

   The condition script will be evaluated before the execution of your code. If it is the case that a value other than true is returned, the code will not execute. The condition is evaluated using the Jira Expression Framework. Event-specific Script Context parameters and variables are listed here for each event. The issue property is not an available Context variable for issue link created events.

7. Write your script in the Code to Run field. This code is executed when the Evaluate Condition is true.

   The Script Context is a set of parameters/code variables that are automatically available in your script to provide contextual data for the script listeners. They are displayed immediately above the code editor beneath the Show Me link. The parameters and variables in the Script Context are different for each Listener Event. Event-specific Script Context parameters and variables are listed here for each event.

   Common parameters in the Script Context for all the events are:

   • baseUrl - Base url to make API requests against. This is the URL used for relative request paths e.g. if you make a request to /rest/api/2/issue we use the baseUrl to create a full request path.

   • logger - Logger to use for debugging purposes. Check the methods available org.slf4j.Logger

   • timestamp - The timestamp of the event in milliseconds e.g. 1491562297883

   • webhookEvent - The webhook event type. Atlassian Connect Webhook Documentation

8. Click Save.

Edit a Script Listener

1. Navigate to ScriptRunner → Script Listeners. A list of all previously created listeners is shown.

   You can check which event triggers have been chosen for each listener by clicking the relevant Event from the list.
   
   
2. Click Edit from the Action ellipsis on the listener you wish to edit.
   
   Similarly, you can also choose the listener you wish to delete by clicking Delete from the Action ellipsis.
   
3. Edit the fields, as required, from within the Edit Script Listener screen.
4. Click Save when all changes have been made.