The Adaptavist Group LogoDocumentation

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.
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.
To run a macro usage report:
  1. Select the Cog icon from the top ribbon in Confluence.
  2. 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:

  1. Click Select next to the list entry.

  2. Search for pages or spaces you'd like to scan. Alternatively, you can select to scan your whole instance.

  3. 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

  1. 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.

  2. If a macro is unsupported, click View detailsunder the Details column to see details of the issue.

  3. 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:

  1. Click Start Migration.

  2. 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.

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.

Note: The rollback banner will not be displayed if the migration was successfully rolled back.

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

Tip: We recommend users disable global numbering to avoid numbering duplication.
Note: Numbered Headings are not supported in blogs.

Limitations for the Aura Apps macros

Please see our dedicated page for limitations on migration support for each Aura App macro.

Search documentation

Start typing to search the docs.