Migrating with draw.io from Confluence Data Center/Server to Confluence Cloud
draw.io has updated the migration process for moving a Confluence Data Center/Server instance to Confluence Cloud with a macro to ensure diagrams are embedded and linked properly, providing no Confluence pages are renamed in the migration process.
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.
The Confluence pageID is used when adding a links to diagrams and for embedding a diagram from one page to another. When a page is recreated in Confluence Cloud, it is assigned a different pageID, often breaking in-diagram links and embedded diagrams.
With draw.io’s migration tool, diagram macros in your Data Center/Server instance will be updated to use SPACE/PAGENAME.
Should I use this new migration tool?
We recommend that you use the older Page IDs method, now that Atlassian supports bulk space permissions editing in Cloud, but 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 (rare) and want to migrate from the Confluence DC/Server 8.0 using this older method
However, if you are using Confluence Data Center/Server 8.0, and you will not rename Confluence pages as part of the migration process, you may find this new migration tool convenient. Follow the steps below.
Run the draw.io migrate tool on Data Center/Server
The draw.io Cloud migration tool must be run on the Data Center/Server instance first, before you migrate to make sure diagram links and embedded diagrams work after migration.
Performing the macro update on the Data Center/Server instance also reduces the number of API calls needed during the Confluence migration, and avoids any problems arising from different administration permissions in Cloud.
Additionally, the draw.io Cloud migration tool sets up the draw.io configuration space in your Data Center/Server instance. Once migrated to Cloud, this is where you can customise draw.io so that all users can use your organisation’s custom styles, custom templates, and custom shape libraries.
Run the draw.io Cloud migration tool
The draw.io Cloud migration is performed by a Confluence administrator.
-
First, stop the Synchrony service that enables collaborative editing. Note that you’ll need to stop the Synchrony service script on the server, not via the Confluence administration console - please refer to Atlassian’s documentation if you don’t know how to do this.
-
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.
-
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. You’ll need to paste this into the draw.io configuration in your Cloud instance in a later step. 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.
-
Perform the Confluence Data Center/Server to Cloud migration as recommended by Atlassian.
-
Once the migration has finished, 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.
-
In your Confluence Cloud instance, go to the draw.io add-on > Configuration section, and select the Configuration tab. Paste the linkAdjustments configuration code you copied in an earlier step into the text field.
-
Finally, to make sure all links are updated and pointing to their correct pages, run a re-index. In the draw.io add-on > Configuration section, select the draw.io re-indexing tab, and click Start Indexing. If you prefer, you can enable Deep Indexing, but as this is a fresh instance, you won’t need to select Clean Diagram Drafts Only.
Why migrate to Confluence Cloud?
Migrating to Confluence Cloud helps you to consolidate IT applications and reduce the load on your local IT support and administration teams.
It’s convenient to have a central Cloud application suite for recording and tracking information both at a corporate level and for distributed teams: task tracking and support requests in Jira, and technical documentation, project planning, and corporate communications in Confluence.
Confluence Cloud has several features and tools that aren’t available in an on-premise or standalone instance, and it is tightly integrated with Atlassian’s Cloud applications. A centralised admin console reduces the workload for IT support, the organisation-wide data privacy and and data storage location rules simplify compliance requirements, and apps are kept up to date automatically.
draw.io works better in Confluence Cloud too - with real-time collaborative editing showing everyone’s cursors. As draw.io is an Atlassian Cloud Fortified app, you can lock down data transmission with configuration options in draw.io and data residency settings in the Atlassian Cloud to keep diagram data between the user’s browser and a Cloud instance in your preferred location.
Tip: Apply a sensitive label to a draw.io diagram to keep it out of Confluence search results.
Learn more about the difference between draw.io for Confluence Data Center/Server and Cloud
Do more with draw.io in Confluence
See how to customise draw.io in Confluence Cloud with custom shape libraries, templates, styles and more.
If you are switching diagramming tools within Confluence with this migration, see how Gliffy and draw.io are different, and mass-import your Gliffy diagrams to draw.io.
If you are using Confluence Cloud and Jira Cloud together, store your versioned diagram files in Confluence, and embed them into Jira Cloud issues.