The Confluence macros that do not survive the move to Cloud
In a Confluence migration the pages move fine. The macros inside them are what break. How to count them, sort them into three groups, find the nested ones, and decide what to rebuild before content owners discover the gaps for you.
A page that showed a live table on Data Center can show a grey “unknown macro” box on Cloud. Nobody notices until the person who relies on it opens it.
Confluence migrations have a reputation for being easier than Jira ones, and for the text that is true. Pages, attachments, comments and permissions move reliably. What does not always move is the behaviour embedded inside the pages: the macros. A macro is a small program sitting in the middle of your content, and it only works on Cloud if something on Cloud knows how to run it.
Why macros are the hard part
Three kinds of macro cause most of the trouble:
- App macros. They come from Marketplace apps, and they render on Cloud only if the vendor has a Cloud app that recognises the same macro and a migration path for its data. Some vendors have both. Some have a Cloud app with a different macro. Some have no Cloud app at all.
- User macros. Written by your own administrators on Data Center, usually as small templates. Cloud has no direct equivalent, so every one of them needs a decision.
- Nested macros. A supported macro inside an unsupported one, inside a table, inside an expand section. If the outer macro breaks, everything inside it breaks with it, including macros that would have been fine on their own.
Count before you judge
The first job is an inventory of every macro in use, with numbers: how many pages use it, in how many spaces, and when those pages were last edited and last viewed.
The shape of that inventory is almost always the same. A handful of macros appear on thousands of pages and drive the plan. A long tail appears on a few pages each. And a surprising share of the tail sits on pages nobody has opened in years. Knowing which is which turns a frightening list of two hundred macros into a short list of decisions.
Sort them into three groups
Every macro then goes into one of three groups:
- Group A: migrates on its own. The vendor’s Cloud app recognises the macro and carries its data across. Verify a sample after the move and move on.
- Group B: migrates with work. A Cloud equivalent exists but differs, or the content needs converting before or after the move. Each of these gets written steps.
- Group C: no Cloud equivalent. Retired apps and user macros live here. The choices are to replace it with a native Cloud feature, rebuild it as a small Forge app, or accept that the content changes.
Group C is where the budget conversation happens, and it goes much better when it comes with page view data. A user macro on four pages that nobody has opened since 2022 is not a rebuild candidate, however clever it was.
Give nested macros their own report
Top-level inventories miss nesting, because they count the outer macro and stop. The only reliable way to find nested macros is to parse each page’s stored content and walk the whole tree. It is worth doing: nested macros are the most common source of “but this page worked in the test migration” surprises, because the test pages chosen by hand were rarely the deeply nested ones.
The report lists, for each page, the chain of macros and which link in the chain is the weak one. That is what a content owner needs to fix it.
Write different instructions for different people
An executive, an administrator and a content owner need different answers from the same assessment. We write them separately:
- For the executive: scope, risk, deadline, budget, and the decisions that are theirs to make.
- For the administrator: the group A, B and C playbook, in the order to do it.
- For the content owner: per macro, what to change before the move and what to check after it.
One page that tries to serve all three ends up unreadable for each of them, and the content owners, who do most of the actual work, are the ones who stop reading first.
User macros: the quiet blocker
User macros deserve a separate warning because they are so easy to forget. They do not show up as an app, they have no vendor to ask, and they were often written by someone who has since left. Inventory them early, pair each one with its page view data, and decide one of three things: a native feature does the job, a small Forge macro does it, or the content changes. Each of those is fine. Discovering them after the cutover is not.
The short version
Pages move; macros are what break. Count every macro with its page counts and view dates, sort them into migrates-alone, migrates-with-work and no-equivalent, parse the content to find the nested ones, and write separate instructions for executives, administrators and content owners. Look at page views before rebuilding anything. And find the user macros first, because nobody else will. If you are planning a Confluence move, this is part of what our Atlassian team assesses.
Planning a move, or cleaning up after one?
We assess Data Center to Cloud migrations, size the ScriptRunner rewrite, move teams off other tools, and clean up what a migration leaves behind. You talk to the people who do the work.
Related reading
After the Cloud migration: cleaning up what the move left behind
The cutover went well. Then the administrators find (migrated) everywhere: duplicate schemes, roles and screens, and notes under every field. Why the duplicates exist, how to consolidate them safely, and how to keep the new site from drifting back into the old one.
Moving off Smartsheet to Jira and Confluence: what lands where
Move everything to Jira is the wrong plan. A Smartsheet estate is many kinds of things wearing the same grid. How to sort sheets by what they really are, migrate only the live ones, use templates instead of one-offs, and handle the formulas, automations and forms that never move on their own.
Sizing a ScriptRunner migration to Cloud before you commit to a date
ScriptRunner is usually the hardest app in a Jira migration, and its estimates go wrong in both directions. How to build a matrix of every script, drop what is dead, collapse the duplicates, translate a first draft to see the real difficulty, and present two honest numbers.