Need help migrating with Mosaic?
Whatever stage you're at, we're here to support your migration. Our team is happy to answer any burning questions or help you move confidently with Mosaic.
Tooltip Macro Migration Guide
Learn how to seamlessly migrate the Mosaic Tooltip macro from Confluence Data Center to Cloud with our step-by-step guide. Ensure a smooth transition with clear instructions and best practices.
This step-by-step guide will walk you through the process of migrating pages containing Mosaic Tooltip macros from Confluence Data Center (DC) to Confluence Cloud.
Currently, Confluence Cloud does not support direct migration of the Mosaic Data Center Tooltip macro and requires users to rebuild their tooltips as Mosaic Cloud Tooltip macros.
Pre-Migration - Prepare for Migration
1. Audit of Macro Usage
Before beginning your migration, identify all pages using Mosaic macros, particularly any using nested macros. Our Mosaic Usage Report tool can help you do this by listing all pages containing Mosaic macros and showing their migration readiness status.
To use the Mosaic macro reporting tool:
- Click the Cog>General Configuration in the top-right corner to open Confluence Administration.
- Navigate to Mosaic Macros.
- Click Mosaic Usage Report.
- Click Start scan. The scan will begin.
- Once the scan is complete, click to Download Report.
Migration - Migrating Pages with Tooltip Macros
1. Run the Atlassian Confluence Cloud Migration Tool
Refer to Atlassian’s documentation for guidance on using the migration tool.
When using the Site Import method:
- Pages are imported into the new Cloud site using the Legacy Editor.
From January 2026
- Pages are imported into the new Cloud site using the Cloud Editor.
2. Review Migrated Pages
The Mosaic for Data Center Tooltip macro does not migrate to Cloud. Once the migration is complete, open the migrated pages that contain Mosaic Tooltip macros. Tooltip macros display as Unknown Macro: ‘tooltip' in the Legacy Editor, and Error loading the extension! in the Cloud Editor. To fix this, pages must be converted to the Cloud Editor and the tooltips rebuilt using the Mosaic for Cloud Tooltip macro.
Need help migrating your Tooltip macros?
If you encounter issues with nested macros, unknown macros, or CSS styling, contact Mosaic support for assistance.
Post-Migration - Upgrade to the Cloud Tooltip Macro
Mosaic Data Center Tooltip macros do not migrate directly to the Cloud and will need to be rebuilt in the Cloud Editor as new Mosaic Cloud Tooltip macros. Rebuilding these tooltips in the Cloud is simple using the new improved editing experience.
1. Convert to the Cloud Editor
Before rebuilding your Tooltip macros as Cloud Tooltip macros, you must convert the page from the Legacy editor to the Cloud editor.
- Open the page you wish to convert and click Edit.
If your page is using the Legacy editor, a notification bar will appear at the bottom of the edit screen. The first time you view a page in the Legacy editor, you can switch to the Cloud editor by clicking Update Page in the notification. - When prompted, click Preview page → Convert Page.
Alternatively, you can choose to preview the page before converting. - The page is converted to the Cloud editor.
2. Rebuild Progress Bar macros using Cloud Progress Bar Macros
Rebuild your tooltips using the Cloud version of Mosaic Tooltip to take advantage of the modern Cloud Editor and CSS-free styling.
- Refer to our Tooltip documentation for step-by-step instructions on rebuilding your macros.
- Enjoy features like simplified editing and consistent styling.
