Getting Started

Features

Configuration

Introduction

Script Listeners respond to one or more webhook events that are fired after an action takes place in Confluence. Examples of events are when a page is created, a comment is added or a new user is created. By using Script Listeners you can create automations based off these webhook events such as:

  • Creating a Jira project whenever a Confluence space is created

  • Automatically watch a specific users 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.

Note - Script Handlers will run for all spaces by default, if you only wish for them to run for a specific space, you will need to include this in your code.

Confluence Events

ScriptRunner allows you to respond to the following events:

Table 1. Events
Type Action

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

Script Context

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 bellow for each event.

How to use it

  • Select the Script Listeners tab in the ScriptRunner menu

  • Provide a name for your Script Listener

  • Select if you want to run this task as yourself or the ScriptRunner Add-on user. Script Listeners can make requests back to Confluence using either the ScriptRunner Add-on user or the user that performed the action to cause the event to be fired. This is useful if you want specific actions (e.g: creating a page) to have the creator as being the current user or a generic ScriptRunner Add-on user

  • Select the event that you want to respond to

  • Add your script

Note - ScriptRunner has a number of example scripts that you can use or update to fit your needs

  • Select save

Table View

Examples

Create Jira tickets when a page is created in Confluence

What does it do?

This can be used to onboard someone such as a to do list or to automatically track work in Jira.

Why should you use it?

Because it reduces time spend on creating the Jira tickets and it establishes and enforces business processes.

Create Jira Issue

Set a watcher for new blog posts

What does it do?

It automatically sets a watcher for new blog posts

Why should you use it?

Because it allows a user to be always following new blog posts from a certain user.

Set a watcher

Company language checker

What does it do?

Checks if a forbidden/incorrect word is used in a page and adds a comment if it is. Let’s say for example JIRA when it should be Jira.

Why should you use it?

Because instead of checking manually for words, one can automate this and ensure that mistakes aren’t made.

An example of this could be raising a note when the text JIRA is added to a page, a comment could be added to change it to Jira.

Set a watcher