Migrate draw.io from one Confluence instance to another

You can migrate the draw.io diagrams from your source Confluence instance to your target Confluence instance via the draw.io app administration.

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

Diagrams with links on shapes that link to a Confluence page, somewhere in your instance contain the Page ID of the target page.

An embedded diagram 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 Page IDs will change. Therefore, to update the links in those diagrams and embed macros so they point to the right pages in the new instance, we must update those Page IDs.

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 in the draw.io app administration.

This works in the same way for all types of Confluence instances, Server, DC or Cloud.

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

Example Page ID migration

We’ll use an example of migrating draw.io from a Confluence Server/Data Center instance to Confluence Cloud.

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 Server instance

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

  1. Go to your Confluence Server/DC 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 Data 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 new Confluence Cloud instance by importing the Page IDs.

  1. Go to your 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 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.