Best Practices and App Management

Best practices for Confluence using ScriptRunner

ScriptRunner helps you automate processes you often use to manage your Confluence instance including data, users, and spaces, which reduces manual effort and potential errors.

The following sections outline automation best practices for Confluence Using ScriptRunner:

The content links you to ScriptRunner for Confluence documentation, Atlassian documentation, and the ScriptRunner for Confluence script library to give you more resources to automate your instance.

🗑️ Cleanup and consolidation

ScriptRunner for Confluence has created ways to automate clearing out old content so that your instance performance doesn't slow down and your users can find the information they're looking for.

Be alerted of old content 🛎️

We have created two scripts to help you identify old content so you can decide if it needs to be archived/deleted or updated. 

Add Label to Outdated Pages

  1. Use this library script to add a label to pages older than a particular timespan using the Script Console or a CQL Escalation Service Job.
  2. Search for that label using Enhanced Search.
  3. Review the old pages returned by the search and act, if necessary.

Old Content Notifier Jobs

  1. Use this job to check pages and their descendants using a CQL clause to determine if there are any inactive pages. 
  2. Review the old content and act, if necessary.

Bulk delete pages

If you've created pages in your Confluence instance that are no longer needed, use the Delete Pages built-in script.

This is both a Confluence Administration Built-In Script and a Space Administration Built-In Scripts. 

You can use the library script Remove Archived Space to remove any archived spaces that have not been updated for over a year.

Bulk update macros

Use the Update Macro built-in script to update macro parameters in bulk within your Confluence instance. 

This is a powerful script. We recommend "spot testing" this script on a sample page

Bulk update pages in a space

The following library scripts are available to work with multiple pages in your space all at one time: 

Delete old content

Use the Automate the Removal of Old or Inactive Content library script to regularly sweep your instance for pages that haven't been updated in a specified period of time and trash them.

To delete outdated Confluence content other than pages, use the following scripts: 

Delete old attachments

Delete old comments

Delete old versions

Use Jobs to remove content based on a schedule. Use the built-in scripts to run a script to remove content based on what's in the script.

Delete trash 🗑️

There are two ways to bulk purge trash: 

Fix links

Use these scripts to fix links in your Confluence instance: 

Manage user content

Use the Change Content Author Built-In Script to change the original Created By author of Confluence content, like pages, blog posts, comments, and attachments. You can use this script if someone is leaving your organization, and they need to hand over pages they created and managed to another user. Or if labels are used by creator for searching and indexing.

Synchronize content

If you have one page set up that needs to be mimicked across different pages, ScriptRunner has four library scripts to help you synchronize different content between pages: 

📈 Content engagement

ScriptRunner for Confluence can visualize how users engage with content and help you identify popular topics. 

Manage watchers

As an administrator, you can make sure your users are watching/getting alerted to certain updated content by adding them as watchers.

Review statistics 📊

Use the Space Statistics Built-In Script to get an overview of your Confluence spaces and view the: 

  • Number of attachments
  • Number of pages
  • Number of blogs
  • Number of comments
  • Number of labels
  • Number of likes
  • Number of trashed items
  • Creation date

The Space Statistics Report:

You can also use this to Cleanup and Consolidate your Confluence instance because the report gives you a view of:

  • Pages older than 1 year
  • Comments older than 1 year
  • Attachments older than one year

Use the Display Spaces View Report library script to view the Spaces View Report in the Script Console.

You can access the Spaces View Report from the Analytics page in Confluence.

⚠️ Data access and security

For information about security vulnerabilities, visit Vulnerabilities and Security. ScriptRunner uses a number of open-source libraries, similar to most apps on the Marketplace. This page covers how we scan for vulnerabilities and common security concerns. 

Permissions and restrictions 🔒

The Manage access and permissions section on this page contains a lot of information about managing user, page, and user permissions and restrictions. Maintaining updated and accurate permissions and restrictions helps your Confluence instance remain secure.

🔋 Data Center and performance

Maintaining a healthy system reduces system downtime and leads to a good user experience with Confluence running smoothly. Using ScriptRunner for Confluence, you can review what's in your instance to determine next steps. Check out the Cleanup and consolidation section to start cleaning up your instance! 

Get notifications for automations 📥

You can use Send Custom Email for Confluence library script to get an email when an automation has finished running.

Similarly, you can send an email based on a Confluence event using the Send Custom Email Listener. For a list of Confluence events, visit Confluence Events and Descriptions. 

Review Confluence content 

There are a number of reports you can view using ScriptRunner for Confluence that gives you a full picture of what your Confluence instance is running. Check these out: 

🔗 Integrations

Seamless integrations create a better user experience, make you more efficient, and limit context switching. ScriptRunner for Confluence integrates with other apps through databases and various scripts to help you automate your process. 

Connect with databases

Connect with relevant databases to make your Confluence instance more useful to your organization. There are two types of database connection:

Adding an LDAP Resource allows you to query your LDAP servers in a similar way to database connections.

Interact with Jira

We've created a number of library scripts to integrate your Confluence instance with your Jira instance: 

Interact with other apps

Here are the different ways ScriptRunner for Confluence has made it easy to integrate your Confluence instance with other apps: 

All Confluence apps

Use the Show User Installed Confluence Apps Library Script to provide a macro to show a list of apps a user has installed on their instance and which macros they provide.

Comala Document Management

Use the Create a Task for Each Page Reviewer Library Script to create tasks within Comala Document Management for each reviewer. Edit the script to specify the tasks you wish to assign and set optional due dates.

Forms for Confluence

Use the scripts outlined on this listener page to automatically create a new page when a form is submitted. For example, you could want a page created when a user submits an internal feature request or events proposal using Forms for Confluence. 

Slack

Use the Slack Connection documentation to set up a connection between your Slack domain and Confluence instance. Once you have this set up, you can use Slack blocks, attachments, and files in your Confluence instance. 

HAPI script 🚀

Work with application links with one simple script using HAPI!


➡️ Migration

To keep a good experience for your users, limit downtime, and reduce admin and maintenance costs, use ScriptRunner for Confluence to automate your migration process.

Visit the Migrate from ScriptRunner for Confluence Server to Cloud section of the ScriptRunner for Confluence Data Center documentation to get started.

A few more links you might find important are: 


🔍 Search and indexing

ScriptRunner for Confluence enables users to quickly find relevant Confluence content through our different search features. You can use these same search features within other features to automate different processes based on those search results (for example, there's CQL search in many of our listeners). 

Add indexing

Add indexing methods to your Confluence content is a great way to yield good search results using CQL Guide search:

  • Page Info Macro: Add various meta data (like Modified By, Created Date, Page IDs, and many others) to your Confluence content.  
    Example CQL to search for meta data: title = "Company Values"
  • Versions History Macro : Add version data about version history to your Confluence content. 
    Example CQL to search for version data: author = admin
  • Work with Labels: Visit the Create and Manage Content Hierarchy section on this page to see the different ways to manage labels to your Confluence content.
    Example CQL to search for meta data: label = 2024

Search your Confluence instance 🕵️

Use Enhanced Search to search your entire Confluence instance (or just parts of it) for anything you want using CQL Guide! 

Use CQL

Use Confluence Query Language (CQL Guide) to perform advanced searches. Advanced searches allow you to use structured queries to search for content in Confluence. 

There are two features that allow you to save custom CQL components to use in your instance frequently:

  1. Custom Search Fields: Create custom search fields to add useful indexes to Confluence's search to find content that meets specific criteria to expand CQL capabilities.

    This is customization for the first component of the CQL Query. For example, in the lastUser = admin query, this is the lastUser part.

  2. CQL Functions: Create custom CQL functions to create and share custom CQL functions (values) with your users in order to empower their search.

    This is customization for the third component of the CQL Query. For example, in the space = allAttachments query, this is the allAttachments part.

CQL can be run anywhere there is a search option in Confluence. You can also run CQL searches in the Script Console by using the Perform a CQL Search in SR4C library script.

We've also created a macro, CQL Search Macro, that enables you to place it on a page where it executes the search and returns the results as links to pages. 

Use SQL to search external databases

If you want to see SQL results from an external database, you can use the Display SQL Results from an External Database Macro library script. This sets up a table using a custom macro on the page where it is used.

Search a page's source 📌

Use the XPath Search in Pages to search a page's source. This can help you identify hidden structural problems in your Confluence content. 

This is an advanced built-in script, and it's more powerful than using a typical Confluence search; however, it takes a long time to run and we recommend only using it on a single space. 


HAPI script 🚀

Search for Pages with one simple script using HAPI!


🔒 Manage access and permissions  

As a Confluence administrator, you might need to manage other users permissions and restrictions based on regulatory standards, confidential information, or to allow for external collaboration. ScriptRunner for Confluence has created several scripts to help you automate permission and restriction management.

For information about permissions required to use each ScriptRunner feature, please visit Permissions. 

Copy permissions

There are two library scripts that automate processes for copying permissions for different Confluence content: 

Display user groups on a Confluence page

Use the Mugshot Gallery Macro to add names and user pictures to a page in Confluence to see everyone in a group. This can be helpful if you want a visual representation of everyone in a group that has access to a space on a page. 

Impersonate users 

The Switch to a Different User Built-In Script allows administrator users to temporarily assume the identity of another user. Switch User has a variety of uses, such as:

  • Reproducing and troubleshooting problems specific to a user to diagnose permissions issues.

  • Updating content on behalf of another user if they are unavailable.

Manage restrictions

There are several scripts we created to help you automate management of page restrictions: 

  • Update Page Restrictions Built-In Script: Replace the editing restrictions to all of the child pages when you select a parent page. You can select multiple pages and page trees to edit restrictions in bulk. 

  • Update Page Restriction Job: Schedule and manage restrictions to parent and child pages. You can automatically add or remove restrictions to entire spaces or pages and manage access for newly created spaces.
  • Update Page Restrictions Listener: Add and remove restrictions to parent and child pages. You can automatically add or remove restrictions to blogs or pages based on a Confluence event.

Use the Inherit Restrictions for Pages Listener to create pages that inherit the parent page restrictions. This script offers administrators the option to specify which spaces should inherit parent page view and edit restrictions automatically.

Remove permissions ❎

There are several library scripts that automate processes for removing permissions for different Confluence content: 

HAPI script 🚀

Run Scripts as Other Users with one simple script using HAPI!

🪪 User license management

ScriptRunner for Confluence has created a few automations to help you manage your user licenses. For general information and help, visit Licensing FAQ. 

Deactivate users

We know there can be limitations with number of users, so we have created a script to help you manage old users. The Check Active User Count and Disable Oldest User library script monitors the amount of users on your instance and disable the oldest user once a certain number is reached.

You can use the Deactivate Inactive Users in Confluence library script to deactivate users based on the time since they last logged in.

Give permissions ✅

With just a username, you can easily re-activate user accounts that have been disabled using the Enable Disabled Users library script.

Update user credentials 

If you have a company event that requires many or all of your user email licenses to be updated, we've created the Update User Emails in Bulk library script to automate the process.

HAPI script 🚀

Work with Users with one simple script using HAPI!


🚧 Create and manage content hierarchy

A clear structure of content enables findability within your space, and ScriptRunner for Confluence has several features and scripts to help you automate hierarchy processes. 

Create templates for complex Confluence instances 🌳

The Automate the Creation of Complex Page Structures within Confluence library script uses a REST endpoint to create complex page structures automatically. You can use this script every time you need the same page tree structure in your instance. 

Move a page

Use the Move a Page When Created library script as a Custom Listener to move a page once it has been created. Using this script will keep the structure, and you can make sure any pages that were created stay together.

Work with labels 

Labels are an easy and effective way to categorize your Confluence content. ScriptRunner for Confluence has several ways to automate label creation and maintenance.

  • Built-in scripts: Manage Labels, a Confluence Administration built-in script, is a one-stop script to add, rename, and remove labels from one or more pages.
  • Jobs: Use the Manage Labels Job to schedule routine label management. You can manage labels on new pages and spaces to help your users find relevant content. 
  • Listener: To automate label maintenance based on a Confluence event, check out Manage Labels Listener.

  • Macros: To create a macro that automatically adds labels to pages where the macro is placed, follow the steps on Add Label Macro or watch this video: 

    To create a macro that adds labels and generates suggested labels on a page if they are not present, check out Choose Label Macro or watch this video: 

  • Library scripts: To add labels to attachments, use the instructions from the Add a Label to an Attachment on a Page library script.

HAPI script 🚀

Work with Labels with one simple script using HAPI!

🛠️ Create and manage spaces

When your spaces are created and maintained well, it increases discovery within your space. Use ScriptRunner for Confluence features and scripts to customize, create, and maintain your spaces.

Customize pages in your space 🎨

Use the Create Page Macro to create a custom page in your space. Watch our video to see the Create Page macro in action:

Or, you can use the Markdown Macro to customize the format of the pages. 

Create spaces based on a template space

If you're managing a large Confluence instance and create a lot of different spaces with the same general format, ScriptRunner can help you automate that process. 

  1. Create a space in Confluence that you want to model the other spaces after. 

    Name it something like Template Space to easily identify it as a template.

  2. Customize the Template Space however you want. 

  3. Use the ScriptRunner built-in script, Copy Space, to use the Template Space to create new spaces.

Delete spaces

The Remove Archived Space library script helps you remove unused spaces in your Confluence instance. 

Maintain spaces by working with pages

Use these built-in scripts to automate simple page tasks within a space: 

HAPI script 🚀

Create a Page with one simple script using HAPI!

 Other documentation

The following links take you to other ScriptRunner documentation that walks you through other best practices, app management, and scripting resources.

On this page