Progress Bar Migration Guide
Learn how to seamlessly migrate the Progress Bar 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 the Mosaic Progress Bar Macro from Confluence Data Center (DC) to Confluence Cloud.
In Confluence Data Center, Mosaic provides:
- Progress Bar Container macro - Wraps and displays a sequence of progress steps within a single bar.
- Progress Bar Hyperlink Step macro - Defines an individual step in the bar, optionally linking to a page or URL.
In Confluence Cloud, these are replaced by:
- Progress Bar Macro - Displays progress as a percentage or series of steps, with customisable style, colour, and layout. No nesting required.
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 icon in the top-right corner to open Confluence Administration.
- Navigate to General Configuration.
- Under Mosaic Macros, click Mosaic Usage Tool.
2. Review Nesting
Confluence Cloud imposes stricter nesting (where one macro sits inside another) limits than Confluence DC. Make a note of any pages containing nested Mosaic Progress Bar macros, as these may need adjustments post-migration.
Pages with extensive nesting, especially when combining third-party and Mosaic macros, may not migrate correctly. If this applies to your content, contact us for tailored support.
3. Assess CSS Style Sheets
If your progress bars rely on the CSS Stylesheet Macro, be aware that this styling will not transfer to the Cloud Editor. Progress bar styling is now set directly within the macro.
- Review pages for any custom CSS.
- Document where these are used, as manual changes may be required.
Migration - Migrating Pages with Progress Bar 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.
- Progress Bar macros appear inside a Legacy Content macro, preserving most of their functionality.
2. Review Migrated Pages
Once the migration is complete, open the migrated pages that contain any Progress Bar macros. Any un-nested Progress Bar macros work as expected in the Legacy Editor in Cloud, with slight formatting differences.
NOTE: Any styling applied using the CSS Style Sheet Macro may not be reflected, as this macro is unavailable in Cloud.
Need help migrating you Progress Bar macros?
If you encounter issues with nested macros, unknown macros, or CSS styling, contact Mosaic support for assistance.
Post-Migration - Upgrade to the Cloud Progress Bar Macro
After migration, Progress Bar macros will remain functional within the Legacy Editor (until January 2026) or a Legacy macro. For the best experience and to make use of all the great features of Progress Bar for Cloud, you will need to convert your pages to the Cloud Editor.
1. Convert 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. All Mosaic Progress Bar macros are now wrapped in the Legacy Content macro and cannot be edited.
2. Rebuild Progress Bar macros using Cloud Progress Bar Macros
To take advantage of the easy-to-use Cloud Editor, you will need to rebuild your progress bar structures using the Cloud version of Mosaic Progress Bar.
- Refer to our Progress Bar documentation for step-by-step instructions on rebuilding your macros.
- Add multiple steps to your progress bar from within one macro.
NOTE: Styling of the progress bar in Cloud is limited. See our documentation for full details on how to build your new Cloud Progress Bars.
Need some help with migration? We're here!
Whatever your question or worry, our team of experts are here to give you clarity.