Guides

Built-in Scripts

What are the Built-in Scripts?

ScriptRunner’s built-in scripts are bits of automated functionality that a Confluence administrator would want to use. Each built-in script does a certain job which typically converts a manual process to a largely automatic operation. The ones found in ScriptRunner for Confluence Cloud are all one-off functionalities that an administrator (or space admin) can use to save massive amounts of time when organizing. To access the built-in scripts, go to the Settings option in Confluence and then Built-in Scripts under the ScriptRunner section. (Your left sidebar menu might have more things in it, depending on what apps you have in your instance, but the ScriptRunner menu is the same.)

Why is this important?

As with so many things that ScriptRunner can do, these built-in scripts provide automation. Confluence has a lot of ways to differentiate and attach information to a page, but sometimes people make mistakes, go overboard, or the processes just change. This is where built-in scripts come in. As an admin there is a lot to keep track of and having to delete or change items one at a time means that the work is incredibly tedious and it’s easy to miss things. Anyone who has seen their careful label system shot to pieces because of misspellings or inconsistent hyphens will recognize the beauty of being able to rename a label in bulk.

The number of available built-in scripts you have depends on what version of ScriptRunner for Confluence Cloud you are running. For any of the scripts, a brief summary is provided on the page and if you need more information or would like a fleshed out example, visit the Developer Documentation. The 8 built-in scripts in this version are:

Bulk Add/Remove Labels on One or More Pages
Bulk Delete Attachments
Bulk Delete Comments from One or More Pages
Bulk Purge Trash
Copy Page Tree
Copy Space
Delete Page Tree
Rename Labels

Adding a Built-in Script

From the main Confluence left side menu, select Settings

Once on the Site Administration menu, select Built-in Scripts, under ScriptRunner

Then choose the script you would like to use.

Complete the required fields. Each script is different and has different fields to fill out. (The screen shot is for Rename Labels)

Note

Labels currently do not support capitalization or spaces. Each space results in an additional label. So in this use case, someone wanted to add the label style guide to several pages but, due to the space between words, actually ended up adding two labels: style and guide. The space administrator is now using the Rename Labels script to change the guide labels to styleguide. He or she also has to pay attention, because if they were to type "Guide" rather than "guide", the Rename Labels script would say that no such label exists.

Going Further

For more information about built-in scripts, see the Built-in Scripts Documentation. For more Getting Started guides, go here.

Script Console

What is the Script Console?

The script console is in some respects the purest form of ScriptRunner, in that it is (without any bells and whistles) a place from which to run scripts. On the Script Console page, you can copy and paste or write a script to run in Confluence. The purpose of this particular area is for experimenting with the Cloud REST APIs or for running the odd one-time script. The Script Console page includes a script editor for you to copy and paste or write your script in. You find a script editor like this anywhere you choose to use a custom script option (so when adding script listener or scheduled job). Code run from the script console can make requests back to Confluence using either the ScriptRunner Add-on User or the Current User.

Why is this important?

The script console is useful for testing scripts or performing operations that you only want to do once. So if you want to grab a list of all the spaces on your instance and some pertinent details about them, you can run a script to do so. Or if you want to delete all spaces that were created by a certain person, you can do that in the script console. It’s also where you run a lot of maintenance scripts that modify something on your instance. If these examples sound like something you could do elsewhere in ScriptRunner, you are probably right. The script console is the heart of ScriptRunner functionality, but depending on what you are doing, you might want to run the script in a different part of ScriptRunner.

Using the Script Console

From the main Confluence left side menu, select Settings.

Once on the Site Administration menu, select Script Console, under ScriptRunner.

Enter the script you want. Some example scripts can be found below the editor box (click one to auto-fill), but you can also write and run your own.

Choose the user you want to run the script and then click Run.

Going Further

For more information about Script Console, see the Script Console Documentation.

Script Listeners

What is a Script Listener?

A script listener, also known as a script event handler or listener, is an automated procedure or function in ScriptRunner that waits (or listens) for a specific webhook to occur in Confluence Cloud.

Webhooks are fired after an action takes place, such as when a blog is created or a space is removed. Just after the event occurs, the listener then takes action based on your requirements. Listeners are very flexible. For instance a listener could create a Jira ticket when a page is created in a certain space for work tracking purposes. Or, if you are a content editor and you know of certain mistakes that are made over and over, you could create a script listener that watches for those mistakes and automatically flags them with an inline comment. For a listener to work, two things have to be defined:

The event (webhook) the listener is waiting for.
The action the listener then takes.

Additionally, you can choose which user the listener is run as. If you need to, you can specify which space(s) the listener applies to in your script (by default listeners run for all spaces.)

Why is this important?

In a standard work environment there are plenty of times when a routine task needs to be accomplished but it is time-consuming to do manually. This is when script listeners are useful. Listeners ensure that you can implement your business’s processes concisely; when the event happens, it triggers an action.

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

Example listeners include:

Create Jira issue when a page is created
Set a watcher for new blog posts
Company language checker

Of course there is much more that you could do with script listeners, these are just some examples.

Adding a Script Listener

From the main Confluence left side menu, select Settings

Once on the Site Administration menu, select Script Listeners, under ScriptRunner

From there, click the Add Listener button.

Enter a name for your listener, choose if you want it Enabled (aka turned on), and then choose at least one event. There are many events options to choose from in the dropdown. Remember, this is the event(s) that causes your listener to run. For our example purposes, we have chosen Content Created and Content Updated.
Select if you want the listener run as the Current User or the ScriptRunner Add-On User. We selected ScriptRunner Add-On User, which means that in the page history you will see the changes made by a special ScriptRunner user.
And finally, write or select the code you wish to run. For our example we chose the example script, Company Language Checker.

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

Going Further

For more information about Script Listeners, see the Script Listeners Documentation.

Script Jobs and CQL Script Jobs

What is a Script Job?

Script jobs (or scheduled jobs) are a way to perform some automated task on regularly occurring intervals. Some examples of scripted jobs are: flagging old content with a "needs-review" label, purging the trash once a month or archiving spaces with no active contributors.

What is a CQL Script Job?

There is one particular type of script job called a CQL (Confluence Query Language) script job (also sometimes referred to as an escalation service.) As the name implies, the CQL script job runs a CQL query. It does so on a specified schedule. Each time it is run, the query returns a number of pages and the job is then performed on/to those returned pages based on the code written. For instance, a CQL script job could change the pages returned by adding comments or deleting attachments etc, but you could also use the results to then fetch a list of child pages.

What is the difference?

The difference lies in the CQL query and it’s mainly a matter of what/how much needs to be done. Jobs can do administrative tasks like adding a label or anything that needs to be created from scratch, typically one at a time. Whereas CQL script jobs can change every piece of content that is returned from a CQL query.

Both use a scheduler and code to perform the actions at the appropriate time. Both types of jobs have a minimum interval of an hour between their code executions. The scheduler is triggered every hour and gathers all the tasks to be executed within that hour. The tasks are queued and executed in no predefined order. That means that the execution time of the task cannot be guaranteed to be the same every hour. As an example: if you configure a job to be run every hour, it might be run at 01:02 and then 02:24 and then 03:00 and then at 04:46 etc depending on how busy the systems are.

Why are these important?

Scripted jobs tend to be useful at automatically tidying things up and preventing content from getting lost or forgotten. When you can have jobs set up to shorten or completely automate what you would otherwise have to do manually, you have more time for other non-maintenance work.

Adding a Script Job

From the main Confluence left side menu, select Settings

Once on the Site Administration menu, select Script Jobs, under ScriptRunner

From there, click the Add Script Job button.

Enter a name, schedule, user, and code for the job. (For this instance, under the code editor box, we clicked the Delete Old Comments example, which automatically fills in the code.) Remember, the schedule cannot be programmed in intervals of less than an hour.

Select Run Now to test it and Save to save the job.
A History section appears after the job has run once and logs each run of the job and you can see the Result and Logs below the job when you are editing it.

Adding a CQL Script Job

From the main Confluence left side menu, select Settings

Once on the Site Administration menu, select CQL Script Jobs, under ScriptRunner

From there, click the Add CQL Script Job button.

Enter a name, schedule, user, and code for the job.

Select Run Now to test it and Save to save the job.
A History section appears after the job has run once and logs each run of the job and you can see the Result and Logs below the job when you are editing it.

Going Further

For more information about Script Listeners, see the Script Listeners Documentation.