Showing results for 
Search instead for 
Did you mean: 
Sign up Log in

Earn badges and make progress

You're on your way to the next level! Join the Kudos program to earn points and save your progress.

Deleted user Avatar
Deleted user

Level 1: Seed

25 / 150 points

Next: Root


1 badge earned


Participate in fun challenges

Challenges come and go, but your rewards stay with you. Do more to earn more!


Gift kudos to your peers

What goes around comes around! Share the love by gifting kudos to your peers.


Rise up in the ranks

Keep earning points to reach the top of the leaderboard. It resets every quarter so you always have a chance!


Handling nested macro discovery at scale in Confluence


I'm busy beavering away in a customer cloud migration, where they make extensive use of macro nesting in historical content, know there are plenty of other customers who also leverage this in Server, DC. Others working in this context will understand some of the challenges of this. You're likely already familiar with

Atlassian recently released this guidance article: which posits this as a customer problem and to start dealing with it in pre-migration work. That can and does involve potential transformation of a lot of content, depending on Confluence instance size, content age and other factors. Content age, relevance and analytics naturally plays a role here, along with business prioritisation approaches for legacy content. Quite the challenge.

Previous related posts have noted the need to do this discovery by brute-force, page by page. That's a little impractical in large instances. I'm interested to hear from others who've tackled this programmatically to help deal with the scale. What's worked? What hasn't? What trade-off approaches have you needed to consider?

3 answers

1 accepted

Suggest an answer

Log in or Sign up to answer
0 votes
Answer accepted

@Brian HillHonestly, we put it on the client.

When nesting is a major problem, it has usually been due to tab macros - macros that let you add tabs and switch between them on the page (e.g. Navitabs).

We provide lists of pages based off (poor) CQL macro searches and they identified critical pages. The critical pages were then checked for nesting and if it was a problem (with this new query, they should all be nested). Most of these were adjusted on Server/DC to migrate without issue, others were updated in a Test Cloud and copied to Prod Cloud. Remaining pages were left up to users post-migration - IT was trained on how to respond to the users.

Given the page content is not something a partner can usually make a decision on, there is not much we can do to directly fix each page.

Our long-term plan is to come up with pathways for various Apps/macros that we can use to advise the customer. We hope to be able to implement some page updates via db/api to handle the simpler macros.

Recently faced issues like that (well, I think it's related) - where native TOC macro doesn't pick up level heading (h2 elements) generated by a custom macro (ACE based).

More context (screenshots) here:

0 votes
Giuliano C_
Atlassian Team
Atlassian Team members are employees working across the company in a wide variety of roles.
Feb 14, 2023

Hi @Brian Hill

I appreciate for bringing up this important topic!

As the author of the article, after going through your post, I have restricted its visibility until we have a clear version to help understand which nesting combinations will not work in Cloud for migrators.

The reason is that the article itself focuses on any sort of nesting and what we want to do is to ensure that customers understand which combinations still work. Thanks to this post, I see the need to improve the article.

Aligned with these reasons, when you migrate to Cloud, the pages will still remain in the legacy editor (which supports nesting). However, some apps did not build the functionality for the legacy editor as well. The current/new editor, on the other hand, does not support nesting for most apps.

Nested-bodied macros in Cloud

Supporting additional nested-bodied macros is something under consideration and we do understand how important this is for migrators, which is one of the reasons for creating articles like the one above!

Even though we are still improving it, whenever you have questions or concerns tied to migration, support will be more than happy to clarify them before going forward with a production migration.

We are interested to know the opinions of other customers and partners regarding the questions that you posted as well! Thank you again for the opportunity, my friend.

Wish you the best,
Giuliano C.
Atlassian Team

Can you at least open it up to partner portal or something? I didn't grab the queries before you locked it down - have had a backlog ticket to write queries for a few months ;)

Giuliano C_
Atlassian Team
Atlassian Team members are employees working across the company in a wide variety of roles.
Feb 20, 2023

Fair point, @Derek White!

I remember you from your comment in CONFCLOUD-70746, which is what the new changes for the KB article will be going through. What a small world, my friend.

After reading your question, I've thought about sharing the queries here, but having it on a page with a warning confirming that this is for all nested-bodied occurrences would benefit other customers and partners without actually confusing them, which is why I just created the KB below:

Can you check it and let me know if it helps? Also, if you have any thoughts about it, I will be more than happy to add them to the KB.

Thank you for the opportunity as well, Derek!

Wish you the best,
Giuliano C.
Atlassian Enterprise Team

Like Derek White likes this

Yeah, I'm all over the place! Co-workers and customers are always telling me they saw a comment of mine somewhere.

We have a migration customer in Test phase, right now, that I can try it out on (this week or next). They use PostgreSQL. Our plan is to, over time, compile a problematic Apps/macros list and be able to attack the most problematic macros earlier in the migration.

Will let you know how it goes, what our process was, what we found, etc.


Like # people like this
AUG Leaders

Atlassian Community Events