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.
   Depending on whether or not you have already created script listeners, you are presented with either a landing screen or a list of the previously created script listeners.
2. Click Create Script Listener from the initial landing screen if none have been previously created. Or, if you would prefer to make use of our built-in examples, click Add Examples to add two script listener examples to your instance.
   
   OR
   Click Create Script Listener from the previously created list.
   
3. (Optional) Click Edit or Delete for your chosen script listener via the Actions ellipsis on this page to modify or delete as required.
4. Enter a name for the listener in Script Listener Called.
   
5. Choose to Enable Script Listener, or turn off to disable.

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

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

8. Enter a condition on which the code will run. You should note that the ScriptRunner Add-on user always runs the condition, but you can choose who runs the script.

   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

9. Choose from either ScriptRunner Add-On User or Current User as the user you wish to run the listener from the Run code as: drop-down options. 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 code as: 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.

   .

10. 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 automatically available in your script to provide contextual data for the script listeners. Choose from the many Examples provided. 
    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

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