Update Macro

This is a powerful script. We recommend "spot testing" this script on a sample page using CQL (e.g. title = "My Macro Update Test Page") to make sure you're getting the parameter updates that you want.

For more information on performance, check out Update Macro Performance. 

Use this script to update macro parameters in bulk. This script updates every selected parameter of the selected macro in pages found by the CQL query. Follow these steps to use the script:

  1. Enter a CQL Query to find pages or blogs where you want the parameter updates to take place.

    This script does not currently work on macros located in comments.


    Select Show Examples for examples you can use.
    Once you enter a CQL Query, the Macro field appears.

  2. Use the Macro dropdown to select the macro you want to work with.
    Once you select a macro, the Macro Parameter(s) field appears.

  3. In Macro Parameter(s), add which parameters you want to update.

    The parameters that are available are the ones that correspond with the selected macro.


    When you select your parameters, the corresponding fields appear.

  4. Enter your new parameter values in these fields.
    For example, CQL and Max Results appear when you select CQL and Max Results for the CQL Search macro.
    New version
  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.

Example: Make Table of Contents Consistent

Using the built-in Confluence macro Table of Contents, you can organize page content and skip directly to the information you're looking for. You can use the Update Macro built-in script to make the table of contents (TOCs) consistent across the Confluence instance.

In this example of the Update Macro script, we update the Maximum Heading Level to for all TOC macros in a specific space. The Maximum Heading Level number is used to limit the headings displayed within the table of contents. For example, '2' will list headings up to 'h2.'

  1. Navigate to Built-In Scripts > Update Macro.
  2. Enter the space you want to update for CQL Query.
    For example, you could enter space = ds to work with a demonstration space.
  3. Enter Table of Contents for the Macro.
  4. Enter Maximum Heading Level for Macro Parameter(s).
  5. Enter 2 for Maximum Heading Level.
  6. Select Run or Preview.
    Selecting Preview gives you a list of pages that will have an updated TOC, but does not update them.

Result: Once you run the script, all TOCs in the Confluence instances will contain heading levels 1 and 2.

Example: Update Code Snippets with a New Version

Using the Mibex Software's Include Bitbucket for Confluence macro, you can provide a branch or tag name from a linked Bitbucket repository to display a specific version of a file.

We use the Include Bitbucket for Confluence macro to display code snippets in our documentation. In this example of the Update Macro script, we replace the tag parameters in pages found by the CQL query containing the Include Bitbucket for Confluence macro to 6.16.0.

We update the parameter whenever we put out a new version of ScriptRunner for Confluence because our code snippets often change.
  1. Navigate to Built-In Scripts > Update Macro.
  2. Enter the space you want to update for CQL Query.
    For example, you could enter space = ds to work with a demonstration space.
  3. Enter Bitbucket File for the Macro.
  4. Enter Git Branch/Tag for Macro Parameter(s).
  5. Enter 6.16.0 for Git Branch/Tag.
  6. Select Run or Preview.
    Selecting Preview gives you a list of all pages that will have an updated code snippet.

Result: Once you run the macro, all code snippets from the linked repository are updated.

On this page