Mosaic Migration Hub
Edit permissions required
To use the Mosaic Migration Hub, you must have Edit permission for the Confluence Cloud instance, and all spaces, and pages you want to migrate. Make sure you have the required permissions before starting the migration. Any spaces and pages you do not have edit permission for will not be included in the migration even if they do appear in the migration scan report.Navigate to the Migration Hub
- Select the Cog icon from the top ribbon in Confluence.
- Select Mosaic Migration Hub under Apps.
Migration
From the Migration tab, you can select which app you'd like to run a migration for. A list of available apps you have installed on your instance is displayed here.
Scan your instance
To scan your instance for macros of the selected app:
Click Select next to the list entry.
Search for pages or spaces you'd like to scan. Alternatively, you can select to scan your whole instance.
Click to scan the selected pages/spaces/instance.
View Scan Report
Click View report in the Details column to view the detailed scan report.The scan report shows each page name, space name, the number of macros, and how many of those macros are supported, partially supported, or unsupported.
If a macro is unsupported, click View detailsunder the Details column to see details of the issue.
Optionally, click Download report to download the report.
Scan reports are not available under the Reports tab. To revisit a scan report at a later date, you must download the report. Click to download a copy of the scan as a CSV file.
Start migration
Once a scan is complete, a migration can be run.
How long the migration takes depends on multiple factors, such as the complexity of macros, the number of macros, the number of pages, and the number of spaces involved.
To run a migration:
Click Start Migration.
Once complete, click Go to Reports. Here you can view a report of the completed migration. See the Reports section below.
Rollback a migration
Once your migration is complete, you can rollback the migration if there are any issues. Rolling back a migration restores macros to their pre-migration state. Any changes made to the macro after migration are lost.
Rolling back a migration is only supported if you have migrated from one of the following apps:
HTML for Confluence - Appfire.
HTML Macro for Confluence Cloud - Appfire.
LaTeX Math - Appfire.
Numbered Headings - Appfire.
It is not supported for the following apps:
HTML macro (Confluence DC) - Atlassian.
Aura Content Formatting Macros - Aura.
Rollbacks are carried out on a report level and will only affect the pages listed in the specific report.
You can initiate a rollback by going to the migration report and clicking Start rollback in the banner at the bottom of the report.
If the rollback fails, the progress bar displayed during the migration turns red, and you can choose Retry to retry the migration or Exit to return to the Reports tab.
When the rollback completes, you can view the status of the rollback in the Reports tab. A status of Rolled back: [date] means that every macro in the report was rolled back. A status of Partially rolled back means that at least one macro was not rolled back.
You can open a report to view a table that shows each page, its space, and whether it was rolled back.
If the migration was only partially rolled back, the rollback banner is still displayed in the migration report, and you can click Start rollback to retry the rollback.
Reports
From the Reports tab, view reports of migrations that have been run on the current instance. A new report is created each time a migration is completed.
Click View Report next to the report you wish to see.
The report lists the pages that contain macros that have been migrated from the selected app. From here, view the page name, space name, migration status, number of successfully migrated macros, and the number of macros which failed to migrate.
If a macro has failed to migrate, click View detailsunder the Details column to see details of the issue.
Supported Apps
Currently, the Mosaic Migration Hub supports migrating to Mosaic from the following apps:
HTML for Confluence - Appfire
HTML Macro for Confluence Cloud - Appfire
HTML macro (Confluence DC) - Atlassian
LaTeX Math - Appfire
Numbered Headings - Appfire
Aura Apps - Aura
Limitations for the HTML macro (Confluence DC) Atlassian
Although we support migrating from the native HTML Macro in Confluence DC to Mosaic, there are some limitations that users should be aware of before migrating.
Sanitisation rules differ between the HTML Confluence DC macro and the Mosaic HTML macro. We suggest running a report before migration to see which macros sanitisation will affect (particularly those relying on url() and @import).
The Mosaic HTML macro runs on Atlassian Forge; Forge macros do not render as expected on pages using a Legacy Editor. Check which editor your pages are using before migration.
Complex macros using interspersed <script> and <style> tags may not show as expected when migrated.
JavaScript is only available for users with Mosaic Advanced Edition.
Limitations for the Numbered Heading macro by Appfire
There are two ways in which Numbered Headings works in Confluence: Byline, which enables numbering at the page or space level, and the Numbered Headings macro.
Numbered Headings macro migration isn't supported in the Migration Hub.
Byline numbered headings are supported, but the following Mosaic settings are not supported and won't be carried over during migration:
Numbering format
Starting heading level
Starting number
Custom heading formats
Limitations for the Aura Apps macros
Please see our dedicated page for limitations on migration support for each Aura App macro.