Move from standalone Capable Approval
If you started with the standalone Capable Approval app and now have Capable for Confluence, you can bring everything across: each page's approval status, approvers, comments and full history, plus your teams, space settings, Slack channel settings and the approval macros on your pages.
The two are different apps, so nothing carries over on its own. The move is a short sequence of steps, and the order matters. Each step checks the one before it is done and refuses to run if it is not, so you cannot get it wrong by accident.
#Before you start
You need | Why |
|---|---|
To be a Confluence site administrator | Every step is administrator only. |
Both apps installed, licensed and up to date | Check Manage apps. An unlicensed Capable Approval cannot export, so do the first step before its licence ends. |
A quiet period, and a word with your approvers | From the first step until a page is imported, its approval is read-only. People can see the status but cannot approve or reject. |
Keep the export file safe. It holds approval comments and the titles of restricted pages. Store it as you would any confidential compliance record. It is also your archive of the approval history.
In both apps the migration controls are in Global settings, on the Approval tab, in the Migration section. Opened from Global settings under Manage in the Approval sidebar, Migration is one of the sections on the page. This is not the separate Migration tab, which holds the Migration Assistant.
#The steps
In Capable Approval, open the Migration section and select Freeze and export.
Approvals become read-only straight away. Bylines and macros keep showing the status, with a note that approvals are moving to Capable for Confluence.
Capable Approval stops reacting to page edits, so nothing in the later steps can reset an approval or send a notification from it.
When the export finishes, download the file. It is named capable-approval-export-<site>-<date>.json.gz, and you can download it again at any time while approvals are frozen. If you need to stop here, select Unfreeze and Capable Approval works as before.
In Capable for Confluence, open the Migration section, choose the export file and select Load. Capable checks the file comes from Capable Approval on this site and shows how many pages, teams and spaces it holds. Nothing is imported yet, but from now on Capable leaves the approvals of those pages alone until each one is imported.
Then open the Migration Assistant. Under Approval for Confluence (Capable), pick Approval macro (Standalone → Suite), run Verify, then Run. Do not choose to keep the source macros. Run it again until no approval page is listed as failed or skipped. The macro migration refuses to start until the file is loaded.
Only the macros change in this step. The approval data moves in the next one.
Back in the Migration section in Capable for Confluence, select Import and keep the tab open while it runs. If it closes, open it again and select Import: it carries on where it stopped and never imports anything twice.
Each page ends up with one of these results.
Result | What it means |
|---|---|
Imported | The approval, approvers, comments and full history are in Capable for Confluence. |
Carried across | The page only changed because of the macro migration, so its approval kept its status. |
Approval requested again | Somebody edited the page after the freeze, so it needs approval again, exactly as Capable Approval would have asked. Its history is kept, and approvers are notified. |
Held: still has a Capable Approval macro | Run the macro migration for it, then import again. You can also import it as it is. |
Retrying | Confluence was busy. The import tries these again by itself. |
If a page already had an approval in Capable for Confluence, the imported one replaces it and the replaced approval is kept. Undo a page puts it back, and Undo all imported pages does the same for every page imported, or partly imported, from the file.
When the results look right, select Finish. Capable stops holding back the migrated pages and handles their approvals normally.
Finishing is final. After Finish, imports can no longer be undone, and pages you did not import keep no approval in Capable for Confluence. Check the results first.
The move changes nothing in Capable Approval: freezing only makes its approvals read-only. Keep it installed and frozen until you are happy with Capable for Confluence, two to four weeks is a sensible wait, then uninstall it and keep the export file.
#What moves and what does not
Moves | Does not move |
|---|---|
Approval status, approvers and their responses, comments and expiry | Authenticator codes. Approvers set up their authenticator again. See Sign approvals with a code. |
The full approval history of every page and blog post | The Slack connection. Connect Slack again; your channel settings are already there. See Slack. |
Teams and team settings. A team whose name is already taken is renamed with "(Approval)" on the end. | People's own notification choices. Everyone sets them again. See Notifications. |
Space approval settings and automation, for spaces with no approval settings in Capable for Confluence yet | Approval macros on blog posts and live docs. Their approval data does move. |
Slack channel settings | Publish targets used by publish on approval. See Publishing. |
Approval macros on pages |
In the history, approvals that came across show an Imported badge. Hover it to see where they came from. See View approval history.
#Going back
Until you uninstall Capable Approval you can return to it at any point. If you already migrated the macros, roll them back first with Roll back in the Migration Assistant, then select Unfreeze in Capable Approval.
Unfreeze checks every page first. An approval stays exactly as it was when only the macro migration, or rolling it back, changed the page. A page somebody really edited while approvals were frozen asks for approval again, as it normally would.
After you uninstall Capable Approval you cannot go back to it, but you can load the export file into Capable for Confluence and import it again.
#A few things that catch people out
Answers from Slack or Microsoft Teams are refused while approvals are frozen. The message says approvals are read-only for now and nothing is applied.
Teams, team settings and space settings the import added stay if you undo. The import never changes ones that were already there.
Once a page is imported, avoid running other migrations on it. Any later change to a page's content, another migration included, asks for approval again.
Never used the standalone app on this site? Select This site has no Capable Approval data in the Migration section instead of loading a file.
#Related
Site settings
Where the Migration section lives.
View approval history
Where imported approvals show up.
Manage approval teams
Teams come across with their settings.
Slack
Reconnect it once the move is done.
Sign approvals with a code
Approvers set up their codes again.
Known limitations
Every boundary, in one place.
Every signature comes with you.
