The Migration Process

Migrating to Confluence Cloud from an existing instance is a big undertaking. Atlassian has developed a migration assistant to help you through the process. You can learn more about it from their documentation.

The general process is as follows

  1. Assess your DC site.

  2. Review apps, users, and content.

  3. Migrate selected content and users using the migration assistant.

  4. Content is moved to your Cloud site and macros are wrapped in a legacy macro in the Cloud editor.

  5. Review and tidy up content in Cloud.

How does Mosaic fit in?

When you migrate your pages over to Cloud, your Mosaic macros will also be migrated inside those pages. The migrated macros will be inside a legacy macro, which allows you limited editing options. For frequently used pages we strongly recommend updating the macros to the cloud versions to improve your experience. 

We know that our macros are likely used across many pages and often combined with each other and even other apps. That’s why we suggest doing a test migration of a small number of spaces to asses if there are any added complications with your migration.

In April 2026 Atlassian made a significant update to how legacy content is handled in Confluence. If you did a test migration before April 2026 we strongly recommend performing another test, as the results may be significantly different. 

Possible challenges

Due to the flexibility that Confluence DC offers users, it is not always possible to smoothly migrate all content to Cloud. We are continuing to work on the migration process but some types of content or layouts present more challenges.

Many layers of nested content

Due to the limitations of Confluence Cloud, it is not possible to place many macros inside each other. If your instance has many macros inside other macros the migrated results will not look the same as the original. The results will depend on which macros are placed inside others and how many layers of macros are combined.

It may be necessary to separate macros or consider options to rebuild the functionality using Cloud macros instead.

Nested third-party macros

If the content you are migrating combines macros from other developers inside our macros then we can not predict how these will appear after the migration. If you are having issues with this you may need to separate the third-party macros from your Mosaic macros.

Extensive use of the CSS Style Sheet Macro

When you migrate content to Confluence Cloud a best effort is made by Atlassian to preserve your existing CSS. However, more complicated applications often fail and can have unpredictable results.

Macros that have the CSS Style Sheet applied to them can also become unsupported in the Cloud Editor.

Macro Migration Guides 

For guidance on how to migrate individual macros, see our Macro Migration Guides on the Mosaic Migration hub. 


On this page