draw.io migration caveats
draw.io is the most exercised migrator we ship and the one with the most hard-won detail behind it. This page collects the caveats so you can read them once rather than discovering them one at a time.
None of these are reasons not to migrate. They are reasons to run a pilot space first.
#Before you start
Verification substitutes a stand-in drawing and never downloads the real file, so a clean dry run does not prove these will migrate.
A macro that was never saved, or whose attachment was deleted, is reported as unsupported (nothing to migrate). Genuine read failures, including permission-blocked pages, are reported as failed so they get investigated.
When a macro pins a specific revision, that historical snapshot is migrated rather than the current drawing. When no revision is pinned, the live copy draw.io keeps wins over the attachment file.
Leftover Gliffy files from an old bulk import are deliberately skipped in favour of the converted draw.io file. If only the Gliffy file remains, the macro is left alone, this migrator does not convert Gliffy.
A diagram still called "Untitled Diagram" is never searched for site-wide, because the name is too generic to trust.
If the same diagram name exists on several pages, Capable refuses to guess and reports the ambiguity with the candidate pages named.
#What survives
The complete draw.io drawing, so shapes, layers, links inside the diagram and multi-tab files all survive
The diagram title, taken from the attachment name
A link to the old draw.io preview image, used for catalogue thumbnails and exports until Capable generates its own
Full version history with each version's original author and edit date, when the migration behaviour version is 1.1.0 or higher
#What does not
The macro's authored width and height, every migrated diagram is created at a standard height
The draw.io border option
The selected tab on a single diagram macro that pointed at a specific page of a multi-tab file
#The three things that most often surprise people
Surprise | What to do about it |
|---|---|
A clean dry run, then real failures | Verification stubs the drawing for draw.io. Pilot one real space rather than trusting the dry run. |
Diagrams arrive without their history | That is behaviour version v1.0.0. Choose v1.1.0 if history matters. |
Every diagram is the same height | Authored width and height are not carried across. Choose the classic layout, or repair it afterwards. |
Zero egress is a separate migrator. If you run the zero-egress build of draw.io, its macros are recognised by their own migrators, listed separately in the wizard.
#A few things that catch people out
Run a pilot space with real diagrams in it. Nothing else tells you what your estate will do.
Do not uninstall draw.io until you have reviewed the migrated diagrams. Rollback restores page content, but the old macros only render while the old app is installed.
Three of the four repair tools exist for draw.io, which tells you where the sharp edges are.
#Related
Pilot one space. It answers everything.
