CQL Escalation Services
Using the CQL Escalation Services built-in job, you can pass the results of a CQL query to the code you provide, which saves you writing the code to execute the query and setting the impersonation context.
For help with CQL, visit the CQL Guide.
Components of the job
Script binding
In the script, the binding variable hits
is available, which is an Iterable<ContentEntityObject>
. Therefore you can do something with each piece of content returned using:
hits.each { content ->
// do something with content
}
Confluence content type information
Depending on your query, the type of content
in the above example will be either a Page
, an Attachment
, a BlogPost
, a Comment
, or another type of Confluence content. However, it will always be a ContentEntityObject
.
If you only want to do something with pages, then use a query that only selects pages like space = "ds" and type = page
. Alternatively, you can use instanceof
in your script to do different things depending on the type of content. An example is title in spaceAttachments("ds")
.
Restrictions
Specify a user that has permission to see the content that you want.
Service code
Your service code is automatically wrapped into a transaction template. Make sure that your service doesn't run for a long time, unless it is a quiet time (like the weekend).
To create the job
Follow these steps to create a job where the CQL query passes results to the script to determine where the action of the job happens.
- Navigate to General Configuration > ScriptRunner > Jobs.
- Select Create Job.
- Select CQL Escalation Service.
- Add a Note to identify the script.
- Select a User to run the script as.
- Enter an Interval/Cron Expression to determine when to run the script.
- Add your Inline Script to determine what the job does with the results from the CQL Query.
Add the CQL Query to pull results to pass to the code in Inline Script.
Determine the type of content you want to pull here.Determine the type of content you want to pull here.
CQL does not support searching on months or years, so multiply the weeks value appropriately.
- Select Add to add the job.
You can also select Run Now to run the script immediately.
Examples
Add Label to Outdated Pages
As a worked example, we’ll add a label to pages that haven’t been modified for one month in a particular space. You may do this if you need to ensure that content is kept current, although this solution is deliberately over-simplistic.
- Navigate to General Configuration > ScriptRunner > Jobs.
- Select Create Job.
- Select CQL Escalation Service.
- Enter the Note Add label to outdated pages.
- Select admin to run the job as in User.
- Enter 0 30 0 ? * * to run the job at 12:30 AM every day.
- Enter the following code for Inline Script:
import com.atlassian.confluence.labels.Label import com.atlassian.confluence.labels.LabelManager import com.atlassian.confluence.labels.Namespace import com.atlassian.sal.api.component.ComponentLocator import com.atlassian.scheduler.JobRunnerResponse def labelManager = ComponentLocator.getComponent(LabelManager) hits.each { page -> // <1> def labelName = "requires-review" def label = labelManager.getLabel(labelName) if (!label) { label = labelManager.createLabel(new Label(labelName, Namespace.GLOBAL)) } if (!page.labels*.name.contains(labelName)) { log.info("Add label to page: ${page.title}") labelManager.addLabel(page, label) // <2> } } JobRunnerResponse.success()
Line 8: Iterate over the items returned from the CQL
Line 19: Add label to the page
- Enter
space = "ds" AND type = page AND lastModified < now(-4w")
for CQL Query.
This returns pages from the Demonstration Space that have not been modified for over 4 weeks. - Select Add.
You can also select Run Now to immediately run the job.
Result: Now, the job will run at 12:30 AM every day and add a label to pages that have not been modified for over 4 weeks.
Add comment to outdated pages
You can also add a comment to any page that has not been modified for over three months and has had no comments in over three months. To set up this script, follow these steps:
- Navigate to General Configuration > ScriptRunner > Jobs.
- Select Create Job.
- Select CQL Escalation Service.
- Enter the Note Add comment to outdated pages.
- Select admin to run the job as in User.
- Enter 0 0 22 ? * SUN to run the job every Sunday night.
- Enter the following code for Inline Script:
import com.atlassian.confluence.pages.CommentManager import com.atlassian.sal.api.component.ComponentLocator import com.atlassian.scheduler.JobRunnerResponse def commentManager = ComponentLocator.getComponent(CommentManager) hits.each { page -> if (!commentManager.getPageComments(page.id, new Date() - 98)) { // <1> log.debug("Adding 'old page' comment to page: ${page.title}") commentManager.addCommentToObject(page, null, "Old page! Please review") } } JobRunnerResponse.success()
Line 9: check we don’t have a comment added within the last three months (in days)
Enter
space = "ds" AND type = page AND lastModified < now("-14w")
for CQL Query.
This selects pages in the the Demonstration Space that has not been modified for over 14 weeks.- Select Add.
You can also choose to Run Now to run the job immediately.
Result: Now, the job will run every Sunday night to add comments to page that have not been modified for over 14 weeks.