Accessing Built-In Scripts

To get to Built-In Scripts, follow one of these tasks based on your permissions:

Confluence Administration

  1. Select the Confluence Administration cog, and then select General Configuration.

  2. Select Built-In Scripts from the ScriptRunner section on the left-hand side of the screen.

Space Administration

  1. Select Space Tools from the bottom left-hand corner of the screen.

  2. Select Advanced Space Functionality.

Alternatively, you can follow these steps:

  1. Open the Space Directory.

  2. Select the space where you have permission by clicking the relevant i icon.

  3. Click on Advanced Space Functionality.

To use a built-in script, click on the built-in script you want to work with.

Browse Built-In Script Functionality

You can use the Search ScriptRunner Functionality search bar to search the available built-in scripts.

Search Bar

For example, if you’re looking for a built-in script that works with restrictions you could type "Restrictions" and press Enter. Then, the list of built-in scripts is narrowed down to only those containing the word "restrictions" in their title or description.

Available Built-In Scripts

The following sections outline built-in scripts for ScriptRunner for Confluence. The order of the following sections follows the order of the built-in scripts on the Built-In Scripts tab.

Add/Remove Restrictions to Parent & Child Pages

In native Confluence without ScriptRunner, editing restrictions that are added to a parent page are not inherited to the child pages. Only view restrictions are supported because they are inherited. This means that pages need to be restricted individually for editing.

With ScriptRunner for Confluence, the Add/Remove Restrictions to Parent & Child Pages built-in script, you can add the editing restrictions to all of the child pages. It is quick and easy to select multiple page trees or individual pages to set page restrictions in bulk rather than having to do it one by one. By selecting a parent page, you’ll apply all the restrictions to that page and all of its descendants.

Follow these steps to run the built-in script:

  1. Fill out Select a Space to implement the built-in script in a certain place.

    Once you select a space, Select One or More Page Trees appears.

  2. Select what page trees you want to work with by selecting the checkbox next to them.

    If you do not select any checkboxes, an error appears that "No space or pages provided."
  3. Pick a value for Select Permissions Level.

    • No Restrictions (Allows Everyone to View and Edit)

    • Editing Restricted (Allows Everyone to View, But Only Some People Can Edit)

    • Viewing and Editing Restricted (Allows Only some People to View and Edit)

      If you select the Editing Restricted or Viewing and Editing Restricted value, two more values appear Choose Groups of Users and Choose Individual Users. Adding specifics groups and users to these fields enforces the restrictions only to those groups.

  4. Select Run.

    You can select Preview instead of Run to view changes before implementing them.

    Once you select Run, the Results of the script appear.

When you select Run, restrictions are applied to the selected page and all ancestors of this page. However, this feature does not override the Confluence permission hierarchy. If you change the permission of a page or set of pages, the restrictions of an ancestor of the page with a higher level of restrictions are observed.

Read more about page restrictions in the Confluence Page Restrictions documentation.

Example Scenario

  • The page "Banana" has a child page "Tiny Banana".

  • The "Banana" page has the restriction level of Viewing and Editing Restricted applied to a user Bob.

  • The "Tiny Banana" page has No Restrictions applied using this built-in script.

Result: The user Bob can’t view the "Tiny Banana" page because the "Tiny Banana" page has inherited the Viewing and Editing Restricted" level of "Banana."

Bulk Add/Remove Labels on One or More Pages

You can add or remove labels on all pages in a page tree using Bulk Add/Remove Labels on One or More Pages. This built-in script can be used to:

  • Specify one or more page trees that require updates to labels.

  • Specify whether to add or remove labels.

  • Specify the labels to be added or removed.

Follow these steps to run the built-in script:

  1. Fill out Space to implement the built-in script in a certain place.

    Once you select a space, Select One or More Page Trees appears.

  2. Select what page trees you want to work with by selecting the checkbox next to them.

    If you do not select any checkboxes, an error appears that "No space or pages provided."
  3. Select the values Add Labels or Remove Labels for Action.

  4. Enter the labels you want to work with in Label.

    For multiple labels, separate them with a space.

  5. Select Run.

    You can select Preview instead of Run to view changes before implementing them.

    Once you select Run, the Results of the script appear.

Bulk Delete Attachments

You can delete all attachments (or all attachments older than a selected time period) for a page or multiple pages using Bulk Delete Attachments. This saves time and energy when there are many attachments that need to be removed.

If the attachment has been modified, the age refers to the modified date not the creation date.

Follow these steps to run the built-in script:

  1. Fill out Select a Space to implement the built-in script in a certain place.

    Once you select a space, Select One or More Page Trees appears.

  2. Select what page trees you want to work with by selecting the checkbox next to them.

    If you do not select any checkboxes, an error appears that "No space or pages provided."
  3. Use the Minimum Age of Attachments to be Deleted to specify age restrictions for attachments for this space. The values for this field follow:

    • Blank (No age restrictions)

      When you select Run, a message appears that alerts you "No minimum age for deletion provided."
    • All (This deletes all attachments)

    • 1 Month

    • 6 Months

    • 1 Year

    • 3 Years

  4. Select Run.

    You can select Preview instead of Run to view changes before implementing them.

    Once you select Run, the Results of the script appear and attachments older than the selected value are deleted.

Bulk Delete Comments from One or More Pages

You can delete all comments, including inline comments, (or all comments older than a selected number of days) for a page or multiple pages using Bulk Delete Comments from One or More Pages. This is useful, for example, when comments become irrelevant due to content changes.

If the comment has been modified, the age refers to the modified date not the creation date.

Follow these steps to run the built-in script:

  1. Fill out Select a Space to implement the built-in script in a certain place.

    Once you select a space, Select One or More Page Trees appears.

  2. Select what page trees you want to work with by selecting the checkbox next to them.

    If you do not select any checkboxes, an error appears that "No space or pages provided."
  3. Use the Minimum Age of Comments to be Deleted to specify age restrictions for comments for the space. The values for this field are:

    • Blank (No age restrictions)

      When you select Run, a message appears that alerts you "No minimum age for deletion provided."
    • 1 Day

    • 1 Week

    • 2 Weeks

    • 4 Weeks

    • 2 Months

    • All (No age restrictions)

  4. Select Run.

    You can select Preview instead of Run to view changes before implementing them.

    Once you select Run, the Results of the script appear and comments older than the selected value are deleted.

Bulk Purge Trash

You can purge all trash for one or more specific spaces or all spaces in your Confluence instance using Bulk Purge Trash.

Follow these steps to run the built-in script:

  1. Fill out one of the following fields:

    • Select the checkbox for All Spaces to use this built-in script for all new spaces in the instance of Confluence.

    • Fill out Target Space for the space you want to work with.

  2. Select Run.

    You can select Preview instead of Run to view changes before implementing them.

    Once you select Run, the Results of the script appear.

The two fields that appear for Bulk Purge Trash are All Spaces and Target Spaces. To purge the trash of all spaces, select the checkbox next to All Spaces. To delete trash from specific spaces, fill out the Target Spaces field. You can then Preview or Run to see results.

Change Content Author

You can change the author of pieces of content (such as pages, blog posts, comments, and attachments) using a CQL query and Change Content Author. The Page History and the Last Modified author of the content is saved. You can only change the original Created by author.

Follow these steps to run the built-in script:

  1. Enter a statment, like creator = username, to select content to work with in CQL Clause.

    Click Show Examples to reveals more CQL examples.

  2. Select the author to work with by using their username in Author.

  3. Select Run.

    You can select Preview instead of Run to view changes before implementing them.

    Once you select Run, the Results of the script appear.

Clear Groovy Class Loader

Use Clear Groovy Caches to manually clear caches if automated clearing fails. Automation should reload classes whenever a script is modified; however, dependent classes can fail to reload.

There are no fields for this built-in script. You just have to select Run or Preview. After you run this script, expect a delay in screen refresh because classes are recompiled when clearing caches.

Example Scenario

If you have a custom class file (ClassA) in your script roots and another Groovy script imports that file, modifications to ClassA may not show up until you modify the script that imports them or clear the Groovy cache with this script.

Copy Space

You can make a complete copy of an existing space using Copy Space. The following data is copied when using this script:

  • Space description

  • Theme, including any custom content and style sheets

  • All content, including attachments, and comments

  • Space templates

  • Space permissions

Page and comment likes are not copied.

Follow these steps to run the built-in script:

  1. Enter the space that you want to copy in Source Space.

  2. Enter the key of the copied space in New Space Key.

  3. Enter the name of the copied space in New Space Name.

  4. Select Run.

    You can select Preview instead of Run to view changes before implementing them.

    Once you select Run, the Results of the script appear.

Copy Page Tree

Use Copy Page Tree to copy a tree of pages to anywhere else. To run the built-in script, you must have permission to view all the pages you are copying and permission to edit the target root page.

Follow these steps to run the built-in script:

  1. Enter a space in Source Space to select the space the page tree is copied from.

  2. Select the checkbox next to the page tree you want to work with in Source Page.

    If you do not select any checkboxes, an error appears that "No space or pages provided."
  3. Enter a space in Target Space to select the page the information is copied to.

  4. Select a checkbox next to the page tree that you want the information to be copied to in Target Page.

    If you do not select any checkboxes, an error appears that "No space or pages provided."
  5. Enter the Title Transformation information.

    To copy a page within the same space, manipulate the titles with a groovy closure because titles must be unique.
  6. Select Run.

    You can select Preview instead of Run to view changes before implementing them.

    Once you select Run, the Results of the script appear.

Example Scenario

When a new version of a product is released, product documentation is released with it. You can copy the entire documentation page tree, version v1.0, using Copy Page Tree. When the next version of the product is released, copy the v1.0 tree and convert v1.0 to v2.0.

Links and image links within the copied pagetree automatically update to reflect any new page titles. If you have a link where "v1.0 Product Doc/Introduction" links to "v1.0 Product Doc/Getting Started", the copied pagetree "Introduction" links to "v2.0 Product Doc/Getting Started."

Prior to upgrading to recent versions of Confluence, you could have created links to pages in Confluence by copying and pasting the URL from the browser address bar. Even though the link works, there are some problems with that method including:

  • Loss of some features (incoming links, for example)

  • Broken links if you change the title of a page

  • Loss of functionality (changing the base URL, exporting the space to another instance without breaking links)

To avoid these problems, use Convert URLs to Confluence Links to convert links to the correct internal storage format. If any page has links that are required to be updated, a new page version is created, allowing you to roll back if necessary.

Convert URLs to Confluence Links handles links with anchors, but anchors are still difficult to use in Confluence because they contain the page name. If a link with an anchor does not work correctly before running this built-in script, the script will not fix it.

Your base URL must be set correctly for this to work, and the base URL must match the full URLs in the pages. If it does not, then the links do not appear as candidates for rewriting.

Follow these steps to run the built-in script:

  1. Fill out one of the following fields:

    • Fill out Space for the space you want to work with.

    • Select the checkbox for Enable in All Spaces to use this built-in script for all new spaces in the instance of Confluence.

  2. Select Run.

    You can select Preview instead of Run to view a list of pages and links that are going to be updated.

    Once you select Run, the Results of the script appear.

Confluence includes JavaScript that automatically creates links with the correct internal storage format when you copy the address, but this functionality does not work on existing content. If you have recently upgraded your Confluence instance, you should only need to run Convert URLs to Confluence Links once.

Inherit Restrictions for Pages

Use Inherit Restrictions for Pages to create pages that inherit the parent page restrictions. By default, new pages only inherit view permissions (not edit permissions) from the parent page, which means you have to set it manually every time a page is created. Inherit Restrictions for Pages overcomes this default and offers administrators the option to specify which spaces should inherit page restrictions automatically.

Follow these steps to run the built-in script:

  1. Fill out one of the following fields:

    • Fill out Space for the space you want to work with.

    • Select the checkbox for Enable in All Spaces to use this built-in script for all new spaces in the instance of Confluence.

  2. Select Run.

    You can select Preview instead of Run to view changes before implementing them.

    Once you select Run, the child pages that you create in the selected space(s) inherit both view and edit restrictions from the parent page.

Inherit restrictions consider parent page restrictions and apply the settings to the newly created pages. The feature does not apply cumulative restrictions from all the ancestors of a page.

Read more about page restrictions in the Confluence Page Restrictions documentation.

Rename Labels

Use this built-in script to rename the labels for one or more specific spaces or all spaces. Follow these steps to run the built-in script:

  1. Specify the spaces that you want to rename labels for by filling out one of these fields:

    • All Spaces checkbox to specify all spaces

    • Target Spaces to pick specific spaces

  2. Specify the label that requires renaming in Target Label.

  3. Specify the new label name in Rename Label.

    Uppercase characters are not allowed in label names.
  4. Select Run.

    You can select Preview instead of Run to view changes before implementing them.

    Once you select Run, the Results of the script appear.

Rename Pages

Use this built-in script to change the titles of pages. Follow these steps to run the built-in script:

  1. Enter the space you want to work with in Pages to Rename.

    Once you select a space, Source Page appears.

  2. Select what page trees you want to work with by selecting the checkbox next to them.

    If you do not select any checkboxes, an error appears that "No space or pages provided."
  3. Use the Title Transformations field to modify the page titles.

    You can select Show Snippets to copy code snippets to help program your page renaming.

  4. Select Run.

    You can select Preview instead of Run to view changes before implementing them.

    Once you select Run, the Results of the script appear.

Space Statistics

Using Space Statistics, you can get an overview of your Confluence spaces showing data such as:

  • Number of pages

  • Number of blogs

  • Number of comments

  • Number of attachments

  • Number of likes

  • Number of labels used

  • Distinct number of users that commented

  • Creation date

To use this built-in script, follow these steps:

  1. Select the space you want to work with in Target Spaces.

  2. Select Run.

    You can select Preview instead of Run to view changes before implementing them.

    Once you select Run, the Results of the script appear.

Switch to a Different User

You can log in as a different user to troubleshoot issues they are having, including:

  • Reproduce and troubleshoot problems specific to a user to diagnose permissions issues.

  • Make updates to content on behalf of another user if they are unavailable.

Follow these steps to run the built-in script:

  1. Choose the user you want to impersonate in User.

  2. Select Run.

    You can select Preview instead of Run to view changes before implementing them.

    Once you select Run, the Results of the script appear.

To switch back to the original user, log out and log in again.

Delete Page Tree

Use Delete Page Tree to move a page (or pages) and all of its children to the trash.

This built-in script works around an issue where deleting a page with child pages caused the child pages to move to the top level of the space.

Using this built-in script requires remove privileges to each page you are trying to remove. If you don’t have permission for one of the pages, then no pages are removed.

Follow these steps to run the built-in script:

  1. Fill out Space to view the contained pages.

    Once you select a space, Pages appears.

  2. Select what page trees you want to work with by selecting the checkbox next to them.

    If you do not select any checkboxes, an error appears that "No space or pages provided."
  3. Select Run.

    You can select Preview instead of Run to view changes before implementing them.

    Once you select Run, the Results of the script appear.

XPath Search in Pages

This is an advanced built-in script. Use XPath Search in Pages to search each page’s source using the provided XPath expression. You could use this script if you require a high degree of control over the presentation of your wiki pages, and you want to make sure everything is correct.

XPath Search in Pages is more powerful for searching for structural problems than the Confluence search, but it is slower. It is best only to run this built-in script on a single space. It takes about 1.5 seconds to search a space with 2,500 pages.

To use XPath Search in Pages, you should be reasonably familiar with the Confluence XHTML storage format, and/or be prepared to examine a page’s source with the Confluence Source Editor in order to work out what expression you need.

Follow these steps to run the built-in script:

  1. Fill out Space to view the contained pages.

    Once you select a space, Pages appears.

  2. Select what page trees you want to work with by selecting the checkbox next to them.

    If you do not select any checkboxes, an error appears that "No space or pages provided."
  3. Enter the expression in Xpath Query.

    Select Show Examples for common expressions to use with this built-in script.

  4. Select Run.

    You can select Preview instead of Run to view changes before implementing them.

    Once you select Run, the Results of the script appear.

Configuration Exporter

Use Configuration Exporter to export extension configuration information to a descriptor YAML file. The YAML file contains the information required to configure built-in extension points like:

  • Listeners

  • Hooks

  • Macros

  • UI fragments

Using the YAML file within script plugins when migrating from one instance to another allows scripts to be automatically configured. Automatic configuration of scripts saves time and ensures consistency across instances.

Follow these steps to run the built-in script:

  1. Select the items you want to generate the YAML for in Export What.

    Items with configurations automatically appear here. Multiple items can be exported to one YAML file.

    configuration-exporter

  2. When the Note field appears, add a note to each item.

    Only items with notes are shown, so make sure each item has one.

  3. Select Run.

    You can select Preview instead of Run to view changes before implementing them.

    Once you select Run, a code snippet appears.

  4. Copy this code snippet and paste it into your scriptrunner.yaml file.

You can manually edit the code yourself to add more items, though it’s generally easier to re-generate the YAML file using the Configuration Exporter script.

For more information on using YAML files to create script plugins see Creating a Script Plugin.

List Scheduled Jobs

Use this built-in script to list all scheduled jobs. There are no fields for this built-in script. You just have to select Run or Preview.

View Server Log Files

Use View Server Log Files to show the last N lines of application log files. Follow these steps to run the built-in script:

  1. Select the log file to view in Log File.

    Your value options are:

    • atlassian-diagnostics.log

    • atlassian-confluence.log

    • atlassian-synchrony.log

  2. Enter the number of lines to display in Number of Lines.

  3. Select Run.

    You can select Preview instead of Run to view changes before implementing them.

    Once you select Run, the Results of the script appear.

Test Runner

Do not run this built-in script in a production instance. It can result in irretrievable data loss.

Use Test Runner to run JUnit and Spock tests, for use in a development instance only. Follow these steps to run the built-in script:

  1. Enter the list of packages to scan for tests in Packages.

  2. Enter tests to run in Tests.

  3. Select Run.

    You can select Preview instead of Run to view changes before implementing them.

    Once you select Run, the Results of the script appear.

CQL Query Conditions

Enter a CQL query, which is similar to a JQL query in Jira. A programming background is not needed to perform one. A CQL query always returns content. The types of content returned by a CQL query are:

  • Pages

  • Blog posts

  • Comments

  • Attachments

The example CQL query below returns all pages in a particular space which were created by a particular user:

space = KEY AND type = page AND creator = username

More examples are given on the Expand Examples part of each script that uses CQL. To learn more about CQL and how to use it effectively, see the documentation.

Space Administration Functions

The scripts listed below are now available in the Space Tools section. These scripts can be used in spaces where the user has space admin permission. Some functionality has been restricted to reflect the lower permission level, but they operate the same as the original scripts outlined above.

  • Bulk Delete Attachments

  • Bulk Delete Comments for One or More Pages

  • Bulk Purge Trash

  • Bulk Add/Remove Labels on One or More Pages

  • Copy Page Tree

  • Copy Space

  • Delete Page Tree

  • Space Statistics

Have questions? Visit the Atlassian Community to connect, share, and learn with other Atlassian users and experts, including Adaptavist staff.

Ask a question about ScriptRunner for JIRA, Bitbucket Server, or Confluence.

Want to learn more? Check out courses on Adaptavist Learn, an online platform to onboard and train new users for Atlassian solutions.