Using ScriptRunner to Bulk Update Macros within Confluence Server

[#1]

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:

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

• How to make the Table of Contents macro consistent
• Updating Code Snippets with a new version

• Updating the Markdown Macro with a new body or URL using the Code Transform field

[Joshua Yamdogo @ Adaptavist]

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?

[Nicolai Sibler]

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,

Nicolai

[Joshua Yamdogo @ Adaptavist]

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)
    }
    macro
}

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!

Regards,

Josh

[Nicolai Sibler]

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,

Nicolai

[Joshua Yamdogo @ Adaptavist]

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. 

Regards,

Josh

[Eduard Grinchenko]

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?

[robert_decomplix_com]

Hi Joshua Yamdogo @ Adaptavist 

I just found this article. Thank you for this information.

We have the use case you inquired in your comment above. We just moved from server to could and need to replace macros, which doesn't exist anymore in the cloud or are not yet available with other macros or text. One of these cases is especially the replacement of the Get-Metadata macro from Comalatech. We use this in a table of page properties with different parameters. So we would not only need to replace the macro but decide depending on the parameter of the macro by which other macro it should be replaced.

Besides that, we need to remove macros which have other macros inside without deleting the macros inside. E.g. at the moment, in the cloud the scroll-ignore macro doesn't allow page property macros inside when a page is converted from the old editor to the new one. Although not optimal, it would be better for us to keep the page property macro without the embedding scroll-ignore macro.

I'd like to know if something of what you mentioned is already on the way.

Regards,

Robert

[Nadine Schuett]

Hello Joshua Yamdogo @ Adaptavist

Thanks a lot for the interesting article.

As mentioned by others and also in your initial comment we need to replace and/or delete entire macros rather than just bulk change macro parameters. 

Do you have any information on how that can possibly be done with ScriptRunner?

Many thanks and best regards

Nadine