Mass import Gliffy diagrams in Confluence Data Center

The mass Gliffy import converts all Gliffy diagrams on all pages (or in the spaces you choose) to draw.io diagrams. Both the current Gliffy JSON format and legacy XML formats are supported.

As a Confluence administrator, you run the mass import in the Gliffy Import tab of the draw.io configuration. It has two tabs:

• Dry run: Find the spaces that contain Gliffy diagrams, test the conversion of the diagrams in the spaces you choose, and review the results. The Read-only tag shows that a dry run doesn't change any page or diagram. You can run it as often as you like.
• Import: Convert the Gliffy diagrams and replace the Gliffy macros on their pages with draw.io macros. The Writes to pages tag shows that the import changes your pages.

These steps are for the draw.io app 16.1.9 and later on Confluence 10, and 17.0.2 and later on Confluence 11. If your Gliffy Import tab only has a Filter by spaces field and a Start Import button, follow the steps in the Older draw.io app versions section below.

Before you start

• Test the mass import on a mirrored test instance first.
• Rebuild the Confluence search index before you scan. The scan reads the search index, so it doesn't find diagrams that are missing from the index.
• The Gliffy app must be installed and enabled while the import runs, because draw.io uses it to read the Gliffy diagrams. You don't need a Gliffy licence.
• If Gliffy is still licensed, users can keep creating and editing Gliffy diagrams during the import. Ask them to stop until the import has finished.
• The scan, the dry run and the import run on the server. You can close the browser tab at any time - the run continues on the server. Only one run happens at a time, even in a cluster.
• The dry run results, your review ratings and the import report are kept in the Confluence database. They are still there after a restart, and they are the same on every node of a cluster.

Open the Gliffy Import tab

1. As an administrator, install the draw.io app.
   • Go to the Atlassian Marketplace heading in the left panel of your instance's administration area, then click on Find new apps.
   • Search for draw.io and install the draw.io Diagrams for Confluence app.
2. Under the draw.io add-on heading in the left panel of your instance's administration area, click on Configuration, then select the Gliffy Import tab. The Dry run tab will be selected, with the Read-only tag next to it.

Step 1: Scan your site and choose the spaces

1. Click Scan site. The scan reads the search index and counts the Gliffy diagrams and macros in each space. It doesn't change anything.
   Note: If the scan finds no Gliffy content, or says that it could not resolve every result, rebuild the search index and scan again.
2. When the scan has finished, the table lists every space that contains Gliffy diagrams, largest first. Already imported counts the Gliffy diagrams that an earlier import has already converted.
3. Select the spaces you want to test. Search for a space by name or key, or use the links above the table to select all spaces with diagrams, all spaces except archived ones, or none (Clear). Clear Show archived to hide the archived spaces. If you don't select a space, the whole site is included. The Scope bar shows what you have selected.
4. Optionally, select Also convert diagrams a previous import already converted. Choose this when you want to convert these diagrams again, for example after you restored pages to their Gliffy version.
5. Click Start dry run to go to the next step.

The scan results are kept until you scan again. If pages have changed since the last scan, click Rescan site. A rescan keeps your dry run results.

Step 2: Do a dry run

1. Click Start dry run. Every diagram in the selected spaces is converted on the server, with the same converter that the import uses. Nothing is attached and no page is saved.
2. Wait for the Dry run complete - nothing was changed message. The counts show how many diagrams converted cleanly, converted with warnings, were imported before or failed, and how many pages the import will rewrite. Problems are grouped under the progress panel.
3. Click Download report to download the dry run report, GliffyDryRunReport.txt.

If a node restarts during the dry run, the dry run is marked as interrupted. Click Start dry run to run it again.

Step 3: Review a sample of the conversions

1. Click Review & report. draw.io selects a sample of the converted diagrams: diagrams with converter warnings first, then a selection across the spaces. To change the sample size, click 50, 1%, 5% or 10%.
2. To see only some of the diagrams, select Unreviewed (diagrams in the sample you haven't rated yet), Flagged (diagrams in the sample with converter warnings) or Failed (diagrams that failed to convert) instead of Sample.
3. Compare the two images. On the left is the preview image that Gliffy stored on the page. On the right is the converted draw.io diagram, as the page will show it after the import. To show both in the same place and flip between them, click A/B or press X.
   Note: If Gliffy didn't store a preview image, compare the conversion with the diagram on its page.
4. Rate the conversion as a Match (press 1), as having Minor differences (press 2), or as having Major differences (press 3). Optionally, add a note. Press the left and right arrow keys to move between the diagrams. Your ratings are saved as you go.
5. To download the dry run report again, click Download report.

Step 4: Import the Gliffy diagrams

The import replaces each Gliffy macro with a draw.io macro and adds a draw.io attachment for each diagram. Nothing is deleted - the Gliffy attachments stay on the page, and every page edit is a normal Confluence page version. Restore an earlier page version to get the Gliffy macros back.

1. Select the Import tab. The Writes to pages tag will appear next to it. The tab shows how many diagrams are ready to import, how many failed conversions will be skipped, how many pages will be rewritten, and when the dry run finished and which spaces it covered.
   Note: You can only start the import after a dry run has completed. The import is also disabled while the Gliffy app is not installed or not enabled, and while Confluence is in read-only mode.
2. Choose which diagrams to import:
   • Import everything that converted: Imports every diagram that converted, whatever you rated it.
   • Hold back "Major differences": The diagrams you rated as having Major differences stay Gliffy diagrams, so you can deal with them later.
3. Optionally, click Advanced. The defaults are right for almost everyone.
   • Comment to put on each page version the import creates: Enter the comment for the page versions. If you leave it blank, Confluence records the edit without a comment.
   • Keep each page's existing "last modified" date instead of stamping it with the import: Choose this when the pages should keep the date of their last real change.
   • Record each converted diagram against the person who last changed the Gliffy diagram, instead of the account running the import: Choose this when the diagrams should keep the name of the person who last changed them.
4. Click Start import. The Confirm mass import dialog lists the spaces that will be imported. Check them, then click Confirm.
   Note: The import runs on the spaces that are selected in the Scan & scope step when you click Start import. If no space is selected, it runs on all spaces. The selection isn't kept when you reload the page, so select the spaces from your dry run again before you start the import.
5. Wait for the Import finished message, then click Download report to download the import report, GliffyImportReport.txt.
   
6. Click Update Drafts once. Some pages may have been open in the editor while the import ran. Update Drafts updates their drafts, so that they don't go back to the Gliffy version the next time someone opens them. It is safe to run it again.

To import the diagrams that you held back, select Import everything that converted, then click Run another import. Diagrams that were already converted are skipped.

If the import stops before it has finished, for example because a node restarted, start it again. Diagrams that were already converted are skipped, so the import carries on where it stopped.

Set the default options with URL parameters

You can set the default values of the import options by adding URL parameters to the draw.io Configuration page's URL:

• pageVersionComment=YourURIEncodedString: The comment to put on each page version the import creates.
• keepDates=1: Keep each page's last modified date.
• keepLastModifier=1: Record each converted diagram against the person who last changed the Gliffy diagram.
• reimportAll=1: Also convert diagrams that a previous import already converted.

For example, replace BASE_URL with the URL of your Confluence Data Center instance:

https://BASE_URL/admin/drawioConfig.action?pageVersionComment=MyComment&keepDates=1

Older draw.io app versions

Older versions of the draw.io app have a Gliffy Import tab without a dry run. You'll find it in the versions before 16.1.9 for Confluence 10, the versions before 17.0.2 for Confluence 11, and the versions for earlier Confluence releases.

1. Under the draw.io add-on heading in the left panel of your instance's administration area, click on Configuration, then select the Gliffy Import tab.
   
2. To limit the spaces you import, enter them in the Filter by spaces field. Use this to test the import on a small demonstration space. Then click on Start Import.
   Note: The full import may take some time, depending on how many Gliffy diagrams there are. When the import has finished, download the text report of the import and use it to check the results.

To add a comment to the page versions the import creates, add the pageVersionComment=YourURIEncodedString URL parameter to the draw.io Configuration page's URL. To keep the date of the last modification of each page, add the keepDates=1 URL parameter. For example:

https://BASE_URL/admin/drawioConfig.action?pageVersionComment=MyComment&keepDates=1

Workaround for the CONFSERVER-59196 bug

On Confluence 7.0.1 to 7.3.2, the draw.io app disables bulk operations such as the mass Gliffy import, because of the Confluence bug CONFSERVER-59196.

As a workaround, update the draw.io app to version 9.2.7 or later and add the ignoreBulkOpsWarning=1 URL parameter to the draw.io Configuration page's URL. For example: https://conf.example.com/admin/drawioConfig.action?ignoreBulkOpsWarning=1

This workaround will simply re-try a failed operation, there is no risk of data loss involved. However, we cannot guarantee that the workaround will be 100% successful.

Gliffy mass import FAQs

When to perform the import

It is better to perform the conversion outside of your company's normal usage hours of the Confluence instance. You can do the import 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.

Tell your users in advance that you will mass import Gliffy diagrams, when you expect to start and finish, and that they should not create or edit Gliffy diagrams during that time.

Diagram backups

draw.io automatically creates a new page revision of every page that contains a Gliffy diagram. You can always revert pages to their previous versions if needed as no Gliffy data is deleted.

Uninstalling Gliffy

Keep the Gliffy app installed and enabled until the mass import has finished and you have checked the result. The import uses Gliffy to read the Gliffy diagrams, so it doesn't work while Gliffy is uninstalled or disabled. You don't need a Gliffy licence for the import.

After you have checked the result, you can uninstall Gliffy so that everyone uses draw.io for diagrams.

Permissions

An administrator who has full write permissions across all spaces in your Confluence instance should run the mass import. If no such user exists, you will need to temporarily elevate an administrator to have those permissions for the duration of the import.

Troubleshooting

Make sure you always test the mass Gliffy import on a test instance with your production data first. If you encounter any issues during this mass import, please email [email protected] and attach the dry run report (GliffyDryRunReport.txt) or the import report (GliffyImportReport.txt).

Related

• See how Gliffy and draw.io differ.
• Mass import Gliffy diagrams in Confluence Cloud.