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 an event to happen before executing the listener script. 

ScriptRunner script listeners run a script when they are triggered by one or more webhook events. Webhooks are fired after an action takes place in Jira, for example, when an issue is updated or a project is created.

How to use Script Listeners

You may want to use a Script Listener to:

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

  • Send an email or notification to a list of emails or all the users defined in a user picker field when the issue is commented on.
  • Transition an issue to another status when it is assigned to a user who is a member of the Developers role using the Issue Assigned event.
  • Automatically update fields for an existing issue when a user edits a specific value for a related field using the Issue Updated event.

On paper, ScriptRunner Script Listeners and post functions seem similar; however, 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

Learn about event-based automating with
Script Listeners
.


Broaden your horizons by exploring the Adaptavist Library for Script Listener examples.

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 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 Evaluate Jira expression

    There are default Context variables "user" (app is not supported yet by Atlassian) and variables specific to the chosen event. For example, for issue-related events, the Context variables will be "issue" and "user". For sprint-related events, the Context variables will be "sprint" and "user". 
    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. Click on the examples under the code field for common use cases that can be edited to suit needs.

    Examples include:

    • issue related events, "issue.comments.map(c ⇒ c.body)" stops the execution as the result is not true but a list of objects

    • issue related events, "issue.comments.length == 2" succeeds for issues with 2 comments

    • sprint related events, "issue.comments.length == 2" errors as issue is not available in the context of sprint event, code will not execute

    • issue related events, "issue.issueType.name.match('^(Bug|Task)$') != null" succeeds only for issues with issue type, Bug or Task

    • issue related events, "issue" stops the execution, you can see the returned value from the execution in the execution detail and check available fields

    • all events, "user.key == 'special-user-key'", runs the code only if the user performing the event is 'special-user-key'

    The Script Context is a set of parameters/code variables that are automatically injected into your script to provide contextual data for the script listeners. They are displayed immediately above the code editor. The parameters in the Script Context are different 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

    Event-specific Script Context are listed below for each event.

  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.