HTML Migration Hub
The HTML Migration Hub is a scanning tool that analyses your existing Confluence content to identify HTML macros created by a selected third-party app. The scan maps which of those macros are supported for migration to HTML by 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 our HTML macro quickly and smoothly, minimising manual effort and reducing migration risk.
Navigate to the HTML Migration Hub
- Select the Cog icon from the top ribbon in Confluence.
- Select HTML 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 HTML 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 Downloadreport 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 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.
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 HTML 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 HTML Migration Hub supports migrating to Mosaic from the following HTML apps:
HTML for Confluence - Appfire
HTML Macro for Confluence Cloud - Appfire
HTML macro (Confluence DC) - Atlassian
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.