Due to the Confluence bug CONFSERVER-59196, the Gliffy mass migration script is not functional in Confluence Server versions 7.0.x to 7.3.x. This bug is fixed with version 7.4, so we recommend you to update your instance. Confluence Server 6.X versions are not affected by this bug .
Switch from Gliffy to draw.io in three steps
This page will guide you through your Gliffy migration. We start with a few basic settings and recommendations before we actually perform the switch to draw.io. The guide is sequential, so just go through it step by step.
Gliffy Migration for Confluence Server
Migrating from Gliffy to draw.io is fairly easy; you can switch with one mouse click. However, we do recommend that you take care of a few things in advance in order to save time and so the converter can run smoothly.
1.1 We highly recommend that you perform the mass import on a test instance first
- Gliffy diagrams with custom shapes or non-standard formatting may not convert to draw.io diagrams correctly at first. This is fixable, don’t worry, but migration on a test instance is always best (follow Atlassian's instructions to create a test instance from your production instance).
- If you can’t create a staging environment, copy important diagrams to a created demo space first and perform the migration for this space only.
1.2 Re-index Confluence so all Gliffy diagrams can be found
- In order to avoid partial or failed conversions, please rebuild the search index (see Atlassian documentation) so the converter can find all Gliffy diagrams later on.
1.3 Check if you have the latest version of draw.io
- If you already have a staging environment and have tested draw.io before, please make sure to update draw.io to the latest version before you start the migration.
1.4 Be sure the Gliffy app is installed (mandatory since draw.io version 9.2.1)
- Gliffy should be installed on your test instance, so that you are able to visually compare the results after the migration.
- The mandatory Gliffy installation doesn't require you to have a Gliffy license. We actually recommend that you remove the license before carrying out the live migration.
1.5 Do you have full permission to access all Gliffy diagram pages?
- The administrator that carries out the Gliffy mass import must have write-permission for every Confluence page containing a Gliffy diagram. Otherwise, the mass importer won't be able to save the draw.io diagram to that page.
- If no such user exists, you will need to temporarily promote a user to administrator status in order to have those permissions during the import.
2. Import Test
2.1 Install the draw.io app
Firstly, access the general configuration area of your Confluence administration panel and install the draw.io app in the Atlassian Marketplace section. After installation, apply the 30-day trial license and select Configuration, which you will find under in the navigation panel under DRAW.IO ADD-ON. Then, click Gliffy import on the draw.io configuration page.
If you've already purchased draw.io for Confluence Server, use your license key together with your Confluence developer license.
2.2 Import the Gliffy diagrams
Click on the Start Import button to import all of the Gliffy diagrams in your instance. You can also use the option Filter by Spaces to import only the diagrams attached to pages in this specific space (good for a quick test on a demo space). Both the current Gliffy JSON and legacy XML formats are supported.
The duration of the import depends on the number and the complexity of the existing diagrams, and doesn't normally take longer than a few minutes. With just one click, all of your Gliffy diagrams within a Confluence instance can be imported into draw.io.
2.3 Download the report
Wait until the import has finished, then use the link beneath the Gliffy import button to download the report. Use the report to see whether all diagrams were converted successfully, and which diagrams were unable to be imported.
You can additionally watch the import test in our video guide.
Things didn't go as planned? Find help on our troubleshooting page:
3. Live Migration
3.1 Outside of working hours
If the report didn’t show any issues with complex Gliffy diagrams you can perform the conversion on your live instance. We recommend that you perform the conversion outside of your company's normal Confluence usage hours. It is possible during normal working hours, but it's best to carry out the whole operation whilst the minimum number of changes are being made to the relevant pages.
3.2 Remove Gliffy license
The recommendation of removing the Gliffy license is so that users do not start editing Gliffy diagrams while the process is running, effectively making Gliffy diagrams read-only. It is worthwhile communicating with users that you are carrying out the migration, and when you expect to start the process.
3.3 Want to keep the original last page modification date and set custom comments to migrated diagrams?
Although the migration doesn’t change the content of the page, (it only replaces the Gliffy macro with the draw.io version of the diagram) a new version of the page with an actual timestamp is created. Some customers like keeping the original date of the last page modification as to not confuse colleagues who might search for content within a specific timeframe. You can configure this just by adding the parameter keepDates=1 to the URL, for example:
You can also set a custom comment applied to converted diagrams (per default the comment draw.io mass import is set) by adding the parameter pageVersionComment=YourURIEncodedString to the URL of the draw.io admin page:
Of course you can combine both parameters, the URL will change as follows:
3.4 Keep you diagrams at original size
In draw.io, diagrams are scaled to Confluence page width by default if the diagram width exceeds that of the Confluence page. Gliffy offers the option to display the diagram macro in its original size, requiring you to scroll the diagram sideways. If you want to maintain this zoom level in draw.io, enter the Confluence edit mode, click on the draw.io macro, select Edit Macro and set the value fixed for the Width setting.
Gliffy Migration for Confluence Cloud
In Confluence Cloud, there are several ways to perform the Gliffy migration. The Premium and Enterprise plans actually allow you to set up a test instance in the form of a sandbox. Learn how to set up a sandbox environment here. Then simply proceed as follows:
- Access your Confluence Cloud settings (you need to have admin rights for these steps).
- If necessary, expand the left settings panel.
- In the Settings panel, go to Atlassian Marketplace > Find new apps and search for draw.io to start a 30-day trial.
- Once draw.io is installed, go to DRAW.IO ADD-ON in the left Settings panel and click Gliffy Mass import.
- Click Start Import and make sure the browser window remains open until the import is completed.
- Copy and save the migration report in case some of the diagrams have not been successfully migrated.
In the Confluence Cloud Standard plan, the migration is done the same way as outlined above for Confluence Premium and Enterprise customers. But, there’s no possibility to test the migration in advance. You can, however, get an idea of the quality of our migration script before the mass migration takes place by performing the following steps in advance:
- Perform the first three steps from the list above to install draw.io in your Confluence Cloud instance.
- Identify the Gliffy diagrams that are the most complex.
- Enter edit mode in the specific Gliffy diagrams and export them (in Gliffy format).
- Insert the draw.io macro on the page where the specific Gliffy diagrams are stored and choose a blank diagram.
- Drag and drop the Gliffy file on the drawing area.
- Save the diagram and the page to compare the draw.io diagram to the Gliffy version.
- If you can't find any discrepancies in these most complex Gliffy diagrams, you can then follow steps four through six from the instructions above.
Things didn't go as planned? Find help on our troubleshooting page:
- No labels