WikiTraccs Creates Draw.io Preview Images

In Migrating Gliffy and draw.io Macros to SharePoint Online we briefly looked into how draw.io macros are migrated to SharePoint Online.

In Support Case: Missing draw.io Images we looked at how draw.io preview images are used by Confluence and WikiTraccs, and how they can be missing.

In this post we work towards a solution to create missing preview images and thus get our images back on migrated SharePoint pages.

Video Introduction to Draw.io Migration and Preview Image Generation

This 8-minute video briefly goes into how draw.io macros are migrated, why draw.io preview images are important for the migration, and how you can use WikiTraccs to bring them back if they are missing:

How WikiTraccs Can Create Missing Draw.io Preview Images

Since the only way to export a draw.io diagram is to show it in a browser first, WikiTraccs will do exactly that.

When encountering a draw.io diagram in Confluence where the preview image is missing, WikiTraccs tries to open the draw.io diagram in the browser to export it as image.

Here’s how that works:

1. a page with draw.io diagram diagram1 is being migrated by WikiTraccs
2. WikiTraccs looks for the diagram1.png preview image; if it is present: fine, us that; if it is missing, continue
3. WikiTraccs opens a browser to show the draw.io viewer, as documented here: https://www.drawio.com/doc/faq/embed-mode
4. WikiTraccs loads diagram1 into the viewer (the diagram should be visible now)
5. WikiTraccs exports the diagram to a PNG image file and uses that from now on

Now there should be a diagram image on the migrated SharePoint page as well.

Note: This works for draw.io diagrams that are stored as direct Confluence page attachment. It won’t work for diagrams that are embedded to the Confluence page from an external location like OneDrive.

Prerequisites for Draw.io Preview Image Generation

The following prerequisites need to be met:

• WikiTraccs must be able to start and control Chrome to show the draw.io diagram viewer in Chrome, and to be able to export the diagram; specifically:
  • Google Chrome must be installed on the machine WikiTraccs is running on
  • Google’s endpoints must be available for WikiTraccs to download the Chrome WebDriver required to remote-control Chrome
• No cookies.txt authentication workaround is being applied (note: this is a rarely used configuration)
• Endpoints required by the draw.io diagram viewer need to be accessible from Chrome, where the diagram view will be shown by WikiTraccs
  • https://viewer.diagrams.net - to load the viewer and image resources
  • potentially more, depending on diagram content

Draw.io Diagram Viewer Showcase

Below you see how the diagram viewer opened by WikiTraccs will look like.

If you see the diagram, the viewer resources seem to be accessible at least from this browser:

To verify the result, here’s a screenshot of how above diagram should look:

Screenshot of the draw.io diagram that should be shown in the diagram viewer above.

How to Enable Draw.io Preview Image Generation

In the WikiTraccs Settings dialog, check Create missing draw.io preview images:

Known Limitations

Currently, there is no indication about external resources in diagram files. (Note: This will change in a future release.) If icons fail to be downloaded by the draw.io diagram viewer, those icons might be missing in the preview image as well. See also the sections External Resources and Blocking External Resources below.

Preview image generation works for draw.io diagram files that are page attachments in Confluence. There is an option to embed draw.io diagrams from external services like OneDrive or Google Drive - those cannot be handled.

In the wild WikiTraccs encountered a broken (?) draw.io macro that failed to properly reference the shown diagram layer which lead to a preview image being empty. So far, this was encountered once but if there is one case, there might be other such cases. Please report if preview images (generated by WikiTraccs) are empty.

Privacy Notes

Diagram data stays local.

To cite drawio.com:

Our […] editor is loaded as a static application […], but the diagram data is passed entirely client-side between windows, it’s never sent back to, or sourced from, the draw.io application server. This means you control and store your data […].

So, while the editor is loaded from viewer.diagrams.net into the browser (to have a canvas to draw the diagram to), diagram data is processed locally.

External Resources

If a diagram contains links to external resources (for example external images not directly embedded in the diagram), the diagram viewer will download those resources. The external host will receive and can observe that request.

Blocking External Resources

When you block direct access to external resource hosts, the diagram viewer doesn’t give up; instead, it downloads resources via a proxy endpoint. This proxy is hosted on viewer.diagrams.net.

A call to the proxy endpoint looks like this: https://viewer.diagrams.net/proxy?url=https://upload.wikimedia.org/512px-Teams.png

So, when you block access to (for example) upload.wikimedia.org in your environment, and if viewer.diagrams.net can be connected to, the proxy will get the image for you.

In this process, the proxy learns about the URL of the external image.

If you want to prevent the proxy learning about external resource URLs, block the proxy endpoint as well. External resources will now be missing in the exported diagram, e.g. icons or images.

• ←Previous
Next→