Migrate draw.io from one Confluence instance to another by updating PageIDs

draw.io data in Confluence consists of two parts:

  • attachments on the pages that contain the diagram data
  • draw.io macros in the pages that use the attachments

draw.io macros either reference diagram attachments attached to that page (most commonly), or contain a Page ID which is the Confluence page ID that the diagram exists on.

All draw.io diagram attachments and macros are migrated as part of your standard Confluence migration. Our migration steps migrate no diagram data.

The issue when you migrate across Confluence instances is that Page IDs change. This migration step isn’t a data migration step, it’s, mainly, a “fix pageIDs” migration step.

This affects:

  • Diagrams with links on shapes that link to a Confluence page, somewhere in your instance contain the Page ID of the target page.
  • Embedded diagrams using the draw.io embed macro stores the Page ID of the page where the original diagram file is attached in the macro.

When creating pages on a new instance, those Confluence Page IDs will change. Therefore, to update the links within diagrams and embed macros so they point to the right pages in the new instance, we must update all the Page IDs in diagram links and embedded diagram macros.

Should I use this Page IDs method, or the new draw.io migration tool?

Now that Atlassian supports bulk space permissions editing in Cloud, we recommend you use the older Page IDs method, especially if you are:

  • migrating from an older version of Confluence DC/Server
  • migrating from one Cloud instance to another or from Cloud to DC/Server
  • you have write permissions to your entire new Cloud instance and want to migrate from the Confluence DC/Server 8.0 using this older method.

The new draw.io migration tool in Confluence Data Center/Server may be more convenient for some administrators. It updates the macros in your server instance first, and avoids problems with inadequate permissions in your Cloud instance, but may cause problems if pages are renamed during migration.

Minimum versions: The new migration tool works with draw.io 11.3.8 and later on Confluence DC/Server 7.x, and draw.io 12.2.0 and later on Confluence DC/Server 8.x.

Migrating using the Page IDs method

In the draw.io app administration, first export the Page IDs from your source instance, and then in your target instance, import the Page IDs via the draw.io app administration.

  • Note that no diagram data is stored outside of your Confluence instance during this process, whether that be Server, DC or Cloud.

  • Both the macros and attachments will port as part of a standard Confluence to Confluence migration. The import and export of Page IDs is only required to update in-diagram links and embedded diagram macros.

Example Page ID migration

We’ll use an example of migrating draw.io from one Confluence Cloud instance (source) to another Confluence Cloud instance (target).

Preparation tips

  • The administrator must have all permissions for both instances (view/add attachments/pages/spaces).
  • Perform a re-index prior to export to make sure Confluence has correctly indexed all page attachments in the source instance.
  • Keep both the export and import Page ID logs generated by draw.io in case an error requires troubleshooting.

Step 1: Export the Page IDs from your source Confluence Cloud instance

Export and save the Page IDs used in diagrams that contain a link to a Confluence page.

  1. Go to your Confluence administration, and select draw.io Configuration in the left panel, then select the Page IDs Export tab.
  2. Click Export data and wait until it the process completes.
    To make sure links in diagrams continue to work, export the page IDs from Confluence to correctly migrate
  3. Once the processing is done, click Download to save the Page ID mapping file to your local device.

Step 2: Import the Page IDs into your target Confluence Cloud instance

Restore the link targets in your draw.io diagrams in the target Confluence Cloud instance by importing the Page IDs.

  1. Go to your target Confluence Cloud administration, and select draw.io Configuration in the left panel, then select the Page IDs Import tab.
  2. Click Start import, select the file you previously saved to your local device, and select Upload. Wait until the import is complete.
    Import draw.io diagram data from another Confluence Cloud instance

Now, those diagrams that contained links should send you do the correct page in your new Confluence Cloud instance. And embedded diagrams should display correctly.

Optional: Re-index your target Confluence instance after importing the draw.io Page IDs to double check that attachments are correctly indexed.