keelapps/Curator/Documentation

Documentation

Curator has one shape, repeated: choose pages, read what would happen to them, then let it happen — and take it back afterwards if it should not have. Everything below is a variation on those four steps.

Where Curator lives

Three surfaces, each scoped to what you can see from it:

• Space → Curator — the space console, for people who can edit the space. Filter the space, choose an operation, read the preview, run it, and see this space's history.
• A page's action menu → Curate this page tree — the same operations over one page and its descendants, without leaving the page. It sees only the batches started from that page.
• Settings → Curator — for site admins only: the label catalogue, renaming, merging and deleting labels site-wide, and the site-wide history.

Whose permissions. A batch runs in the background, where Forge has no user to act as, so its changes are made with Curator's own permissions. Before anything is queued — and again when you press Run — Curator checks you: you must be able to edit the page the batch starts from, the space's home page for a space-wide batch or the root of the tree. Page restrictions bind Curator too: a page whose view restriction does not include it is invisible to it, so it is neither previewed, counted nor changed.

Two operations reach further than editing, and need more: archiving needs what archiving in Confluence needs — space admin, or the space's Archive permission — and moving needs the right to add pages where the pages are going. The list of destination spaces shows only the spaces you can see.

Selecting pages

A selection is a filter, not a list of ticked boxes, so it keeps working as the space grows. The available criteria:

• Scope — a whole space, or one page and its subtree.
• Title contains — a substring match.
• Last updated — before a date, after a date, or between two.
• Created by — the person who created the page.
• Has all of these labels — every one must be present.
• Has none of these labels — the exclusion half.
• Include archived pages — off by default.

Curator counts the matches before you choose an operation, so the first number you see is “how big is this?” rather than “what did I just do?”.

The operations

Moving into another space is expressed as “move under this page”, because Confluence's move API takes a target page rather than a space. Curator resolves a space you pick to its home page for you.

The dry run

Nothing is written until you have read a preview. Every preview answers the same five questions:

• How many pages change, out of how many matched.
• The first fifty, individually, each with the exact edit it would receive — not “labels will be updated” but which labels, on which page.
• How many are skipped, and why. Every skip reason gets its own sentence: already has the label, no edit permission, archived and excluded, the move target is inside the selection, and so on. A page never disappears from a batch without an explanation.
• What it will cost, in Confluence API points.
• Whether it can be undone.

A preview describes the site as it was when the preview was built, so it stops being runnable after 24 hours. Build a fresh one rather than trusting a day-old description of a space other people have been editing.

Undo

Every run records a per-page inverse as it goes: the labels to put back, or the parent page and space to move the page back to. Undo replays that journal.

A label batch is undone by taking off exactly the labels it added and putting back exactly the ones it removed; nothing else on the page is touched. A moved page is guarded: before Curator moves it back it checks the page is still under the parent this batch left it under. If it is not, somebody has moved it since, and Curator leaves it where they put it and names it in the undo's result. A partially applied undo is an honest outcome; a silently reversed decision is not.

The undo is itself an operation in the history, with its own counts and its own record of who ran it.

The label catalogue

Settings → Curator → Labels lists every shared label on the site with a usage count. It is for site admins only, because Curator builds it with its own access: it names labels from every space, and Confluence shows a person only the labels they may view.

Those counts are derived. Confluence's label endpoint returns names and ids and nothing else — there is no count in the payload — so Curator walks each label's pages in the background and counts them itself. Every row therefore carries the time its count was taken, and counts past two thousand are shown as 2,000+ rather than pretending to a precision the walk did not buy. Pages Curator cannot see — a view restriction that does not include it — are not counted.

Confluence can hold one label name several times over: adding a new label to many pages at once can create several labels with the same name. Curator treats them as one label — one row, one count, and a rename that reaches every page carrying the name.

Personal favourites — the labels Confluence stores with a my prefix — are never listed and never touched.

Renaming, merging and deleting labels

Settings → Curator, site admins only. Three operations, all site-wide, all previewed and all undoable:

• Rename — every page carrying the old label ends up carrying the new one.
• Merge — one label is folded into another on every page that carries it.
• Delete — the label is detached from every page that has it.

Confluence has no rename or merge endpoint, and Curator does not pretend otherwise. A label is a string on a page, not an entity, so a rename is a bulk edit: remove the old label and add the new one on every page carrying it. That is not an atomic operation — it is hundreds or thousands of individual page edits, and it can be interrupted. Which is why this is exactly where the dry run, the resumable checkpoint and the whole-batch undo earn their keep. A run that stops halfway resumes from its checkpoint; a run that finished wrong can be reversed.

History and CSV export

Every run and every undo becomes one history record: the operation and a description of it, the selection it ran over, the space, the acting person's name, start and finish times, how many pages succeeded, were skipped or failed, whether it can still be undone, any note you typed, and up to a hundred per-page failures with their reasons.

History is capped at 2,000 entries per site; beyond that the oldest are dropped. Each space's history is in its space console; the whole site's is in Settings → Curator → History, for site admins. Export either as CSV whenever somebody needs the trail outside Confluence.

API points and pacing

Confluence Cloud charges apps for API calls in points, and the hourly allowance belongs to the app — shared across every customer running it, not per-site. Exhausting it would block every other site until the next hour. Curator therefore meters itself in three places:

• The dry run prices the batch before you commit to it.
• An operation too large to be neighbourly is refused, with a reason — not queued to run overnight at everyone else's expense.
• Anything below that ceiling is paced: when this site has used its share, the batch pauses and resumes in the next hourly window from its checkpoint.

A long batch that says “paused until the next window” is working as designed. It will finish.

What Curator cannot undo

Archiving. Confluence Cloud has no API for restoring archived pages — CONFCLOUD-75065, the request for one, is still Gathering Interest — so archive is the one operation Curator cannot take back as a batch. The pages are not lost: Confluence restores them under Space settings → Content → Archived, one at a time, or on Premium together with the pages nested under them. Curator says so in the preview, on the Run button and on the finished batch.

Archiving also depends on your Confluence plan. Page archiving is part of Confluence Standard and above, and a Free site refuses it: Curator stops the first such batch with that reason and blocks archive previews from then on. The archive API also takes a limited number of pages per call and runs one archive task per site at a time, and Curator paces itself to both.

Permissions the app requests

There is no permissions.external block: the app cannot make an outbound call even if it tried to, which Atlassian enforces at the platform level.

Not in this release

• Attachments — deliberately out of scope. See Satchel for Confluence.
• Deleting pages. Curator archives; it never deletes.
• Editing page content or page titles.
• Changing page or space permissions and restrictions.
• Scheduled or recurring batches.
• Cross-site operations.

Support

Questions, bug reports and feature requests: raise a support request. Security issues: report privately.