Migrating Confluence Whiteboards as draw.io Files

Note: The whiteboard to draw.io conversion is available as of WikiTraccs v1.34.1.

In the last blog post I wrote about why you can’t really export Confluence whiteboards - Atlassian only offers manual PNG / JPG / PDF export, no structured format, no supported API.

WikiTraccs now offers something on its side: a best-effort conversion of Confluence whiteboards into draw.io files, alongside the existing PNG migration.

What This Means

Instead of (or in addition to) a flat PNG image as page attachment, your migrated SharePoint page can carry a .drawio file that contains the whiteboard’s shapes, text, colors, and connectors as editable elements.

You can open .drawio files in:

• draw.io / diagrams.net (the web editor at https://app.diagrams.net/)
• The draw.io app for Confluence (if you’re using draw.io there too)
• The draw.io desktop app
• Various IDE plugins (VS Code, IntelliJ)

In short, the whiteboard becomes editable again, not just a screenshot.

How to Enable

It’s a Gray Setting - meaning it might not be fully supported by a vendor - and it’s labeled as best effort. Enable it in the WikiTraccs settings: Migrate whiteboards to draw.io file [Cloud, best effort].

This is independent of the existing Migrate whiteboards (export as image) setting. You can enable just one, both, or neither:

• Just the image - same flow as before, you get a PNG.
• Just the draw.io conversion - you get an editable .drawio file.
• Both - both end up on the migrated page.
• Neither - whiteboards are skipped.

What to Expect

The conversion translates the whiteboard’s structure into draw.io’s diagram model:

• Shapes (rectangles, ellipses, rounded rectangles, …) - preserved with positions, sizes, fill and stroke colors.
• Text inside shapes and free-floating text labels - preserved.
• Connectors between shapes - preserved with their endpoints.
• Stickers (the Atlassian sticker library used in whiteboards) - included as best-effort image references. Not all stickers are supported yet; support will be extended over time.
• Stacking order - mostly preserved; what was on top in Confluence is on top in draw.io.

It is not a pixel-perfect copy. Whiteboards are a free-form canvas; draw.io is a diagram editor with stricter rules. Expect:

• Slight differences in spacing, padding, or font rendering.
• Some elements (highly custom text formatting, freehand drawings, certain stickers) may not transfer faithfully.
• Curves and complex connectors may straighten out, lose bending points, or bend differently.
• Stacking order is preserved in the common case, but on whiteboards with a long edit history it can occasionally come out different than what you see in Confluence.

Disclaimers - Same Spirit as the Image Export

Just like the image-based whiteboard migration, this is a workaround for something Atlassian doesn’t (yet) offer themselves. That means:

• WikiTraccs reads whiteboards the same way the Cloud editor does. When you open a whiteboard in Confluence, the editor pulls the same whiteboard data WikiTraccs reads for the conversion. So as long as a whiteboard renders in your browser, WikiTraccs has access to the same content. Atlassian just doesn’t offer a separate, supported export on top of that.
• When Atlassian evolves the whiteboard format, WikiTraccs follows. Confluence’s whiteboard product is under active development. When Atlassian changes how whiteboards are represented, WikiTraccs needs an update to keep up. Until then, the conversion may produce incomplete results for whiteboards that use the new format.
• Best effort means best effort. The converter understands the shapes, text, connectors, and other elements it has been taught about. If a whiteboard contains something the converter doesn’t yet recognize, that element will be missing or simplified in the .drawio output; the rest of the whiteboard still comes across. New element types are added over time.
• Confluence Cloud only. Server / Data Center whiteboards are a different product and are not covered by this conversion.

If a conversion looks wrong: file an issue and attach both the raw binary whiteboard data (.bin file) and the converted .drawio file so the converter can be improved. You can grab both either from the SharePoint page attachments of a migrated whiteboard page, or via the diagnostic exporter (see next section).

A Quick Way to Test the Whiteboard to Draw.io Conversion

You don’t have to start a full migration to see what your whiteboards look like as .drawio files.

WikiTraccs’s Diagnostic Bundle Export (Tools → Create Diagnostics Report → enter a whiteboard’s content ID → click Fetch Confluence XML → click Assemble + zip) packages a single whiteboard’s full data, including:

• the raw binary diagram data file (the whiteboard’s underlying snapshot),
• linked resources used by the whiteboard (e.g. images, stickers),
• the converted .drawio file.

Open the diagnostic bundle, find the .drawio file in the whiteboards/<id>/ folder, and open it in draw.io. That’s the same file you would get from a real migration with the setting enabled - minus all the rest of the migration plumbing.

It’s the fastest way to answer “would this whiteboard come out usable?” before committing to a migration run.

Wrap

The image export gives you a screenshot. The draw.io conversion gives you something you can keep editing.

Neither is officially supported by Atlassian, both are Gray Settings, and either can break when Confluence Cloud changes shape. They complement each other: PNG is the safe baseline, draw.io is the upgrade for when you actually want to keep working with the content after migration.

Try it on a representative whiteboard via the diagnostic bundle export, see how the conversion looks for your data, and turn the setting on for the migration run if it fits.

• ←Previous
Next→