Create
cancel
Showing results for 
Search instead for 
Did you mean: 
Sign up Log in
Deleted user
0 / 0 points
Next:
badges earned

Your Points Tracker
Challenges
Leaderboard
  • Global
  • Feed

Badge for your thoughts?

You're enrolled in our new beta rewards program. Join our group to get the inside scoop and share your feedback.

Join group
Recognition
Give the gift of kudos
You have 0 kudos available to give
Who do you want to recognize?
Why do you want to recognize them?
Kudos
Great job appreciating your peers!
Check back soon to give more kudos.

Past Kudos Given
No kudos given
You haven't given any kudos yet. Share the love above and you'll see it here.

It's not the same without you

Join the community to find out what other Atlassian users are discussing, debating and creating.

Atlassian Community Hero Image Collage

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

5 comments

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?

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

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

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,

Nicolaiscreen.jpg

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

Comment

Log in or Sign up to comment
TAGS
Community showcase
Published in Confluence

Miss the Confluence demos at Team 21? Watch them here!

Phew, Atlassian Team 2021 blew by. With dozens of demos and a handful of keynotes, you may have missed some of the awesome Confluence Cloud sessions. Don't' worry, you can watch them all here or on Y...

227 views 2 6
Read article

Community Events

Connect with like-minded Atlassian users at free events near you!

Find an event

Connect with like-minded Atlassian users at free events near you!

Unfortunately there are no Community Events near you at the moment.

Host an event

You're one step closer to meeting fellow Atlassian users at your local event. Learn more about Community Events

Events near you