nav[aria-label="Primary Navigation"] { padding: 0; & ul { list-style: none; width: 100%; display: flex; flex-direction: row; justify-content: start; align-items: start; gap: 30px; padding: 0; & li { margin: 0; } & ul li { list-style: none; } } }

How did you handle user macros when moving Confluence to Cloud?

Chayut Jarriyarponrung

Hi everyone,

I'm a developer looking into one migration problem: Confluence Cloud has no user macros, so they break after moving from Data Center.

If you've done this migration (or are planning it), I'd love to hear:

About how many user macros and pages did you have?
What did you do with them?
Which ones were hardest to replace?

I'm thinking about building a tool to convert them automatically, but I want to understand the problem first. I'll share a summary of the answers here.

Thank you!

Comments

Viswanathan Ramachandran

Hi,

Welcome to the community.

I'm sure you must have done the homework using usermacros and bodycontent DB queries on the usage and decided which ones to migrate. See this if you're looking to build custom Forge apps to replace your macros: https://developer.atlassian.com/platform/app-migration/tutorials/p2-to-forge-macros/

I believe there are No marketplace apps that does the direct migration, you can check these

Adopt apps like Content Formatting for Confluence or rely on Native Cloud Editor layouts/panels for UI and formatting macros.
Use Space Content Manager or Bob Swift CLI to batch-replace deprecated markup and bulk remediation.
Build a lightweight Forge Macro and map it via CCMA for any other logic.

The hardest part: It depends on how your macros are configured. Programmatic APIs like java, DOM/CSS injectors, any macros that are fetched behind your company firewalls could be challenging.

Note: You can let the community know for any questions and for additional more help contact Atlassian support.

Also, share your success story, challenges and learning as well, so it could help others.

Chayut Jarriyarponrung

Thank you, this is really helpful! I should have been clearer: I'm a developer, not migrating myself. I'm trying to understand the problem so I can build something useful.

So far I've built a small Forge app that scans a Cloud site after migration and lists every macro that shows "Error loading the extension!", with how many pages use each one.

Two questions, if you have time:

In the migrations you've seen, do admins usually know which macros broke, or do they find out from users later?
Have you used Space Content Manager or Bob Swift CLI for this? What was missing?

Viswanathan Ramachandran

To answer your questions:

do admins usually know which macros broke, or do they find out from users later?

Mostly yes, but honestly, it comes down to thorough testing in sandbox/stage instance. Involve couple of business users/space members to participate in your testing.

have you used Space Content Manager or Bob Swift CLI for this? What was missing?

In my experience, I used CLI and for evaluation only I used Space Content Manager. Both are effective, serves it purpose, but each has specific gaps depending on your use case:

Use Space Content Manager if you want space owners and admins to self-serve and clean up straightforward UI macros across their own spaces.
Use Bob Swift CLI or Python REST scripts for automated, repetitive replacements across the entire site prior to migration.

For complex macros with custom logic, map them to a Forge macro using Atlassian's App Migration Platform.

You will know the complex macros from the admins. Ask them to export the macros from the database, discuss with them which one they need help and support.
They can run rest apis, CQL search or python scripts to find pages with 'unknown macro' error. The storage format from the page(s) gives all that information.

You can work collaboratively with your admins and Atlassian support.

Admins can raise a ticket with Atlassian support. They will share the details that support requesting.
Atlassian support finds the cause and share it back with your team. If that needs some development work, you will have those details and then you develop your code and try the fix.

Chayut Jarriyarponrung

Thank you, this is really useful and changes how I think about it. It sounds like experienced teams handle the "finding" part well with scripts and testing. In your experience, which part takes the most time or budget: deciding what to keep, rebuilding complex macros in Forge, or cleaning up pages afterwards?

Welcome!

It looks like you're new here. Sign in or register to get started.

Quick Links

Find more posts tagged with

confluence

migration

user-macro

cloud-migration

confluence-data-center