Mosaic Migration Hub

The Mosaic Migration Hub is a scanning tool that analyses your existing Confluence content to identify macros created by a selected third-party app. The scan maps which of those macros are supported for migration to Mosaic, providing a clear overview of compatibility.

After selecting the source app and running a scan, users can view a report and migrate supported macros to Mosaic quickly and smoothly, minimising manual effort and reducing migration risk.

Warning:

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

To run a macro usage report:

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.

After a scan has been run, a table is displayed. This table shows the number of pages scanned, the number of macros found, and the number of macros supported, partially supported, or unsupported.

Warning: You must have Edit permission on the pages and spaces being scanned. Any pages or spaces you do not have permission for may be included in the scan but cannot be migrated.

Tip: We suggest selecting a small number of pages for migration before running a migration at scale.

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 details under the Details column to see details of the issue.
Optionally, click Download report to download the report.

CAUTION:

Scan reports are not available under the Reports tab. To revisit a scan report at a later date, you must download the report. Click View Report → Download Report 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.

Tip: Migrations will run in the background, so it is safe to navigate from this pag

Warning: Once a migration has started, it cannot be stopped. However, a migration can be rolled back once complete

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

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.

The 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