Script Listeners

A listener is an automated procedure or function in ScriptRunner that waits (or listens) for a specific event (or web hook) to occur in Confluence Cloud. Events are fired after an action takes place, for example, when a blog is created or a space is removed. Just after the event occurs, the listener takes action based on your requirements. 

For a listener to work, two things have to be defined:

  • The event (webhook) the listener waits for

    Examples of events are when a page is created, a comment is added, or a new user is created.

  • The action the listener takes

Additionally, you can choose which user the listener run as. You can also specify which space(s) the listener applies to. By default, listeners run for all spaces.

Use cases

Listeners are very flexible. In a standard work environment, there are plenty of times when a routine task needs to be accomplished but is time consuming to do manually. Listeners ensure that you can implement your business’s processes concisely. 

Example listeners include:

  • Create a Jira ticket when a page is created in a certain space for work tracking purposes

  • Set a watcher for new blog posts

  • Watch for frequently made mistakes and automatically flags them with an inline comment (helpful for a content editor)
  • Create a Jira project whenever a Confluence space is created

  • Watch a specific user's content in a space

  • Create a templated 'about user' page when a new user is created

  • Automatically add a label to a new page to notify users that it requires review.

Use Listeners

ScriptRunner for Confluence enables you to write your own listeners in a script editor box using the script file and/or events you want. Additionally, below the editor box, several different examples of things you might want to do are provided (and automatically fill in the script when clicked.)

  1. From the main Confluence left side menu, select Settings.
    Table View

  2. Select Script Listeners, under ScriptRunner.
    Table View

  3. Select Create Script Listener.

  4. In Script Listener Name, enter a name for your listener.

  5. Choose if you want it Enabled (or turned on).

  6. Choose at least one event for On These Events.
    Remember, this is the event(s) that causes your listener to run. These are the available events:

    TypeAction

    Attachment

    Created, Removed, Restored, Trashed, Updated, Viewed

    Blog

    Created, Removed, Restored, Trashed, Updated, Viewed

    Blueprint Page

    Created

    Comment

    Created, Removed, Updated

    Connect Addon

    Enabled, Disabled

    Content

    Created, Permissions Updated, Restored, Trashed, Updated

    Group

    Created, Removed

    Label

    Added, Created, Deleted, Removed

    Login

    Login Event, Login Failed

    Logout

    Logout Event

    Page

    Children Reordered, Created, Moved, Removed, Restored,Trashed, Updated, Viewed

    Relation

    Created, Deleted

    Search

    Search Performed

    Space

    Created, Logo Updated, Permissions Updated, Removed, Updated

    Theme

    Updated

    User

    Created, Deactivated, Followed, Reactivated, Removed

  7. For As This User, select if you want the listener run as the Current User or the ScriptRunner Add-On User.

  8. And finally, write or select the code you wish to run in Code to Run.

    Script contexts

    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. Check out Atlassian Connect Webhook Documentation for more information.

  9. Select Save

Built-in examples

ScriptRunner has a number of built-in example scripts that you can use or update to fit your needs. You can select the example under the Code to Run field.

Create Jira Tickets When a Page Is Created in Confluence

Create Jira Tickets When a Page is Created in Confluence can be used to onboard someone, like a to-do list or to automatically track work in Jira. It's useful because it reduces time spent on creating the Jira tickets, and it establishes and enforces business processes.
Create Jira Issue

Set a Watcher For New Blog Posts

Set a Watcher For New Blog Posts automatically sets a watcher for new blog posts. It is useful because it allows a user to be always following new blog posts from a certain user.
Set a watcher

Company Language Checker

Company Language Checker checks if a forbidden/incorrect word is used in a page and adds a comment if it is. For example, it could catch JIRA because it should be Jira. It is useful because instead of checking manually for words, a user can automate this and ensure that mistakes aren’t made.

Set a watcher

Once you have filled in the example code, you may have to do some editing to make the code work as you want it to. For example, you have to add the terminology that is a problem in your instance.