Script Listeners

Before you start

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. 

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.
   You will see the Create Script Listener screen, as shown below:
   
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 apply only to events related to issues, projects, issue links, versions, and comments. If you need to filter issuelinks for both the source and destination issues, be sure to include both projects in the filter.

   The location of the outward link in the issue defines the mapping that is required, for example:
   If Project A is mapped, and ISSUE-1 in Project A is assigned a “blocks” link to another Issue, this means ISSUE-1 is the outward link that fires the Script Listener. If Project A is mapped, and ISSUE-1 in Project A is assigned an “is blocked by” link, this means ISSUE-1 is the inward link, which would not fire the Script Listener since it is not mapped.

   
   

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.

   Script context

   The Script Context is a set of parameters/code variables automatically available in your script to provide contextual data for the script listeners. 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

10. Write your script in the Code to run: field. This code is executed when the Evaluate Condition is true.
    OR
    Alternatively, you can click the Example scripts button to view a list of example scripts related to this feature.
    
    So, rather than writing your own script, you can reuse one of the many examples provided, as follows:
    

    1. Choose an example script from the list provided and the code automatically appears. You also have the option to search for a particular script.
    2. Click Copy Code and then Close.
    3. Paste the copied code in the code editor.

11. Click Save. You can test your script using the Run Now button, which will execute the script and return the results.

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.

Examples of Additional Bindings and Parameters

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 above the code editor under the ‘Show Me’ link. The parameters and variables in the Script Context are different for each Listener Event. 

Related content

• Take our ScriptRunner Tour.
• See our Example Scripts for Script Listeners.