Migrate draw.io from one Confluence instance to another
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 pageID which is the Confluence page ID that the diagram exists on.
All draw.io attachments and macro are migrated as part of your standard Confluence migration. Our migration steps migrate no data.
The issue when you migrate across Confluence instances is that pageIDs change. This migration step isn’t a data migration step, it’s, mainly, a “fix pageIDs” migration step.
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.
- 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.
- Go to your Confluence Server/DC administration, and select draw.io Configuration in the left panel, then select the
Page IDs Export tab.
- Click Export data and wait until it the process completes.
- 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.
- Go to your Confluence Cloud administration, and select draw.io Configuration in the left panel, then select the
Page IDs Import tab.
- Click Start import, select the file you previously saved to your local device, and select Upload. Wait until the import is complete.
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.