Support Case: Missing draw.io Images

In Migrating Gliffy and draw.io Macros to SharePoint Online I briefly explained how draw.io macros are migrated to SharePoint.

The post briefly describes how there are two assets for each draw.io diagram in Confluence:

• the draw.io raw diagram file (file without extension)
• a preview image of the diagram (PNG file)

From time to time clients encounter cases in their environment where the preview image is missing. What are the consequences of a missing preview image?

How Is the Preview Image Used in Confluence?

Let’s look at this page, which has two diagrams, one with its preview image missing:

The attachments list looks like this; note there is only one preview image present (preview-image-available.png), I manually deleted the other one:

Looking at above screenshots, let’s start with the one place where the missing preview image is no issue: the actual diagram on the Confluence page. So, you don’t immediately notice that the preview image is missing when looking at the page, as the diagram is properly shown.

Missing in Page Edit Mode

When editing the page this looks different. Apparently the preview image is required here:

Sometime a placeholder is shown, like above, sometimes there is a “broken image” icon.

Missing in Page Exports

The diagram will be missing in page exports.

Here’s the PDF export of our sample page that contains two draw.io diagrams; but only one shows up in the export:

Missing in Emails

There are use cases in which Confluence page content is sent via email. Those uses cases also rely on the preview images being present.

If the preview image is missing, the image won’t show up in the email that gets sent.

Missing in REST API Integrations

There are REST endpoints that can be used to export macros in automated scenarios.

Normally, data returned by those endpoints contains the image (if the macro has one). The PlantUML macro is one such example where a proper image is being generated and returned. Or the Roadmap macro.

Those REST endpoints can be used by tools like WikiTraccs to further process the page, or other script-based solutions that further process the page.

For draw.io, if the preview image is missing, it will be missing for all REST API consumers as well.

Missing on Migrated Page in SharePoint

WikiTraccs relies on the preview image to be present. It’s what’s shown on the SharePoint page.

If the preview image is missing, no image can be shown.

Note that the raw draw.io diagram file will be migrated as page attachment and could theoretically be downloaded and opened in the draw.io desktop application.

How to Check If I Am Affected?

Draw.io provides a built-in integrity checker that is available to Confluence administrators:

The integrity check will also check for missing preview images.

The integrity check result then looks like this:

The following diagram images were not found:
Total: 1
Macro: drawio, on page: http://wiki.contoso.com/pages/viewpage.action?pageId=22183937, Diagram image file not found: preview-image-missing.png (version: 1)

Unfortunately, draw.io doesn’t provide a repair function.

Version Note: Tested on Confluence Data Center 8.7.1 with draw.io version 13.1.10.

How to Get The Preview Image Back?

There seems to be only one way, to get the preview image back: edit and save the draw.io diagram in the browser.

Saving the diagram is the moment where the preview image is created and stored.

The preview image seems to be created in the browser, which would explain why there is no other mechanism to trigger the generation of this image. The draw.io diagram has to be open in a browser. Only then is it available to be saved to file by the draw.io editor.

Let me know if you know of another way to get the preview image back.

Confluence Cloud and External Sources

In Confluence Cloud, using the Embed draw.io Diagram macro, it’s possible to include draw.io diagrams that are stored in OneDrive and other cloud locations.

When you visit a page with OneDrive integration for the first time, the following message will be shown:

"Authorize draw.io to access OneDrive"

When clicking the message, you’ll be asked to authorize draw.io:

"Authorize draw.io to access OneDrive"

After giving authorization, the diagram should be shown. Unless there is a permission error.

In case of permission error, the following message will be shown:

"Error: Access Denied. File not found or you do not have permission to access 'diagramname.drawio' on OneDrive."

When the access issue is resolved, the diagram will be shown.

Now the caveat.

In none of the above cases - even if the diagram is shown - will the preview image of the diagram be generated. Thus, there will be no image in SharePoint Online since it’s only in the diagram macro that the image is being rendered.

This is a technical limitation.

• ←Previous
Next→