draw.io data in Confluence consists of two parts:

• attachments on the pages that contain the diagram data
• draw.io macros in the Confluence 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.

The draw.io migration tool doesn’t migrate any data, it replaces the Page IDs with SPACE/PAGENAME where necessary in your Data Center/Server instance:

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

Should I use this new drawio migration tool, or the import/export Page IDs method?

The new draw.io migration tool in Confluence Data Center/Server updates the macros in your server instance first, and avoids problems with inadequate permissions in your Cloud instance. We recommend you follow the steps below if you can see the draw.io migration tool in your DC/Server instance administration.

Minimum versions: The new migration tool is for 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.

If you prefer, you can use the older Page IDs method 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 (rare) and want to migrate from the Confluence DC/Server 8.0 using this older method

Use the draw.io migration tool to migrate your Confluence DC/Server instance

As a Confluence administrator:

1. First, stop the Synchrony service script that enables collaborative editing on the server, not via the Confluence administration console - refer to Atlassian’s documentation.

2. Go to the draw.io add-on > Configuration section, and select the Cloud Migration tab. Click Start to update links within the diagram macros.
   
   You will be reminded that you need to stop the Synchrony service. Click OK to continue.
   

3. When this process is complete, click on Download Data to save the report, and copy the linkAdjustments configuration command that appears to a safe location. For example:
   { "linkAdjustments": [{"re":"^/display/", "r":"/wiki/display"}]}
   
   This step also creates a new space called draw.io Configuration in your Data Center/Server instance that you can use in your new Cloud instance to customise draw.io.
   

4. Perform the Confluence Data Center/Server to Cloud migration as recommended by Atlassian.

5. Check that the space permissions for the new draw.io Configuration space in your Cloud instance are set to the following: All admins can write, and all users can read.
   

6. In the draw.io add-on > Configuration select the Configuration tab. Paste the linkAdjustments configuration code you copied in an earlier step into the text field.
   

7. In the draw.io add-on > Configuration section, select the draw.io re-indexing tab, and click Start Indexing.