Run a migration
The migration wizard is on the Migration tab of the app's global settings. It walks through five steps, and the one that matters most is the last: verify first, read the results, then migrate.
Every page the migration changes gets a new version labelled "Migrated by Capable", so any page can be put back from its page history. A large migration is still worth doing deliberately.
#When this applies
Actually running the migration, once you have decided to.
Migrating a large site in stages rather than all at once.
Re-running after fixing whatever caused failures.
#How it works
Step | What happens |
|---|---|
1. Introduction | How the run works (Find, Verify, Migrate, Undo) and what to confirm before you start. |
2. Options | How the run behaves. See the table below. |
3. Select apps | Pick the apps you are moving away from, such as draw.io. |
4. Select macros | Choose the macros to migrate in each app. Optionally narrow the pages with a filter, for example one space, recently edited pages or a label. Then choose Perform verification or Start migration. |
5. Run | Progress and results page by page. A verification is marked Dry run, nothing is written; when it finishes you can select Start migration from there. |
#The options
Option | What it does |
|---|---|
Skip errors | Keeps going when one macro or page fails, and logs the failure. Turn it off to stop at the first failure. |
Keep source macros | Leaves the original macro on the page and adds the Capable macro next to it, so you can compare them in a pilot space. Pages show both until you clean up. |
Keep diagram version history | Under Advanced options. Replays each draw.io and PlantUML diagram version by version, keeping original authors and dates. Much slower on a large site. |
Classic draw.io layout (beta) | Under Advanced options. Keeps migrated diagrams at the size and alignment they had in draw.io. |
Use Admin Key (experimental) | Under Advanced options. Migrates pages you cannot normally edit. Without it, restricted pages are skipped and reported. |
#A few things that catch people out
Verification runs over real pages but writes nothing. It is the cheapest way to find out what the real run will do.
Leave the browser tab open until the run finishes. Large spaces take time, so migrate in batches.
To undo, restore pages from Confluence page history one by one, or use Roll back pages with the run's migration log to put every page it changed back to its pre-migration version.
Pages you cannot edit are skipped and reported as permission failures, unless you use the admin key option.
For the short version, see Migrate from draw.io to Capable Diagrams in Confluence.
#Related
Verify first. Every page can be put back.
