Come for the products,
stay for the community

The Atlassian Community can help you and your team get more value out of Atlassian products and practices.

Atlassian Community about banner
Community Members
Community Events
Community Groups

Using ScriptRunner to Bulk Update Macros within Confluence Server

Hello everyone! 😃

Following up on my colleague @Jonny Carter's blog post about how to use ScriptRunner to bulk update content contained within Confluence pages, I figured I should come back and write about a feature we recently released in ScriptRunner that makes bulk updating macros incredibly easy.

We spent a significant amount of time developing this with the hope that it will save you the hassle and time required to manually edit pages. 😃

Script overview

In a large Confluence instance where a macro is used hundreds of times across many pages, Update Macro helps Confluence admins to:

  • Save hours of work by adjusting macro parameters and macro content in bulk instead of having to manually edit each appearance
  • Keep things consistent by ensuring information is displayed and surfaced for reporting in the same way across various macros

Update Macro works on native Confluence macros and third-party macros alike. It is simple to use and doesn’t require any scripting, but there is an option for scripting if needed. 

Our script is a potential answer to the feature request Atlassian has open that describes user's desire to easily update or change many macros at once.

Basic usage of the script

Update Macro was initially released in version 6.22.0 of ScriptRunner and then enhanced in version 6.25.0. So, you'll need to be on version 6.22.0 at the minimum.

Once you've installed a version of ScriptRunner which has the Update Macro script, you can simply locate it by visiting the Built-in Scripts page within ScriptRunner. 

After clicking on the script, you'll see several fields.

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

  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.
    When you select your parameters, the corresponding fields appear.

  4. Enter your new parameter values in these fields.
    You do not need to enter a Code Transform - it is optional. You could also skip Step 3 above and just enter a transform.

For example, you'd get the following fields if you selected parameters for the Confluence's Blog Posts macro:

Screen Shot 2021-05-18 at 3.45.17 PM.png

We have developed this script so that users get dynamically generated fields that make sense in relation to the macro parameters that are selected. For example: the Restrict to these Authors parameter for the Blog Posts macro will generate a User Picker field, because you'll need to select users.

Simply click Run after filling in the fields and all found macros will now be updated! 🎉  🎉

Documented examples


Something we've considered is the use-case of wanting to replace one macro with another macro entirely. We believe it should be possible to do within the Code Transform field... but we're not sure how common this use-case is. Has anyone ever needed to completely replace a macro with another macro?

Like # people like this

Hi @Joshua Yamdogo _ Adaptavist ,

thanks for the insights!

I have a complex use case and I wonder if the Update Macro will do the job:

We are using a 3rd party app which has a field to restrict the usage of the macro to both usernames and groups in a comma-separated list. In a new version, there's an additional field to define users and groups in their own fields.

As the set parameters of the macros in our instance are very diverse, I wonder if the Update Macro could identify usernames or groups from the one field and put them into the new one. Is it possible to run that abstract job?

Best regards,


Hey @Nicolai Sibler,

Thanks for the question! think this should be possible, but it would help to know exactly which third party app it is. Here's some sample code with comments that you would use in the Code Transform field.

import com.atlassian.confluence.xhtml.api.MacroDefinition

macroTransform = { MacroDefinition macro ->
//get old parameter value
def oldParameterValue = macro.parameters.oldParameter

// extract user and group values from the old parameter value
// def users = oldParameterValue
// def group = oldParameterValue

// set new parameters with extracted values
if (oldParameterValue) {
setMacroParameter(macro, 'userParameter', userValue)
setMacroParameter(macro, 'groupParameter', groupValue)

Essentially, you'd exact the value from the old parameter and then set the two new parameters. I think the difficult part would be knowing how to split up the value from the old field to know which values in the comma separated list are user or group values.

Let me know if that's helpful!



Like Nicolai Sibler likes this

Hey @Joshua Yamdogo _ Adaptavist ,

thanks for the answer!

The plugin in question is called "Survey and Vote Macros". We are currently still using a 2.x version.

Technically, the field will remain as it is now and will become a field for groups in version 3.x. This means that Users will remain in that field, but will lose their permission if they are not transferred to the new field. The new field becomes the field for individual Users. In this new field there is a user picker; the User is then no longer displayed, but the Full Name.

Both Users and Groups are named with an alphanumeric combination in our instance. However, all groups have a dash or underscore in their name and the User identifiers do not.

As I understand it, the extraction could work like this:

All values with a dash or underscore remain in the old field (because they must be groups) and all values without a dash or underscore are transferred to the new field (because they must be individual Users).

What do you think?


Best regards,


Hi @Nicolai Sibler ,

Sorry for the slow reply... I was on holiday.

All values with a dash or underscore remain in the old field (because they must be groups) and all values without a dash or underscore are transferred to the new field (because they must be individual Users).

Yes, I think you have it exactly correct. 😃

I would try writing the Macro Transform code to do this and running the script on just one test page that has the macro. See if it works.

Let me know if you run into trouble. I'd be curious to see your code. 



Hi @Joshua Yamdogo _ Adaptavist ,

Thanks for the nice article!

We need exactly what you said in the first comment. We want to replace one of our own old macro with the new one and also update parameters for it. How can we get more information about it?


Log in or Sign up to comment

Atlassian Community Events