Migration options
Four switches sit on the Options step alongside the version picker, two of them behind Advanced options. Two are safe to leave alone; two change the outcome enough to be worth understanding first.
All of them apply to verification as well as to the real migration, so a dry run reflects the settings you are about to use.
#At a glance
Option | Values | Default |
|---|---|---|
Skip errors | On / Off | On |
Keep source macros | On / Off | Off |
Classic draw.io layout (beta), under Advanced options | On (classic) / Off (Capable Auto) | Off |
Use Admin Key (experimental), under Advanced options | On / Off | Off |
#Skip errors
On, an individual macro or page failure is logged and the run keeps going. Off, the run stops at the first failure. Verification always behaves as if this is on, regardless of the setting, so one dry run surfaces every problem.
Leave this on unless you are debugging a specific failure and want the run to stop at it.
#Keep source macros
On, the original vendor macro stays on the page and the Capable macro is added next to it, so nothing is removed and the two can be compared side by side in a pilot space. The page then renders its content twice until you clean up. This is not self-cleaning: re-running later without the option converts the page properly but does not remove the duplicates, which have to be deleted by hand. It also means the source macro still matches the search, so the page is revisited on every subsequent run.
This is the one that surprises people. With Keep source macros on, the page renders its content twice, and running again later without the option converts the page properly but does not remove the duplicates. They have to be deleted by hand.
It earns its place in a pilot space, where seeing the old and new macros side by side is exactly what you want. It is a poor choice for a real run.
#Classic draw.io layout (beta)
On, migrated draw.io diagrams keep the size and left alignment they had in draw.io, in a frame that hugs them. Off, Capable's Auto layout scales the diagram to the column width. Changing your mind after a migration means editing every macro by hand or running the Repair diagram layout tool. It does not apply to zero-egress embed references.
This one is repairable after the fact. Repair and rollback includes a tool that switches migrated diagrams between the two layouts in bulk.
#Use Admin Key (experimental)
On, page counts and the run itself send the Confluence admin key header so restricted pages can be read and migrated. Off, restricted pages are skipped and reported as permission failures. The switch grants nothing on its own: the admin key must first be activated in Confluence under Settings, Security, Admin key, and it expires on its own timer, so restricted pages start failing if it lapses mid-run. Toggling it re-fetches every page count.
The switch grants nothing on its own. The admin key has to be activated in Confluence first, under Settings, Security, Admin key, and it expires on its own timer. If it lapses part way through a long run, restricted pages start failing from that point on.
#A few things that catch people out
Options are chosen two steps before the run buttons, and the wizard never brings you back to them. Changing one means clicking back through the rail.
Toggling the admin key re-fetches every page count, so the counts step reloads.
The classic layout option is not applied to zero-egress embed references. Treat that as an observed limitation rather than a designed behaviour.
#Related
Two safe switches, two that change the outcome.
