Bulk Page Operations

Bulk Page Operations for Confluence

Move, copy, label and archive up to 500 selected Confluence pages in one job, after a dry run shows you what will happen to each page.

Bulk Page Operations is a Forge app for Confluence Cloud. It adds a page to each space's settings. You pick pages with CQL or by choosing a parent page, pick what to do with them, check the dry run, and start the job. The job runs from the open page, a few pages at a time and as you, while you watch its progress. You can cancel it, and you can undo label changes later.

What it does

You can select pages in two ways.

• CQL, such as label = "draft" AND lastmodified < now("-180d"). The app always adds space = "<this space>" AND type = page around your query, so a job can't reach pages in other spaces. An ORDER BY is dropped, and unbalanced quotes or parentheses are refused before anything runs.
• A parent page (ID or link) and everything below it, with or without the parent itself.

The dry run

Nothing changes until you've seen a preview. It lists every selected page with one of three results.

• Will change.
• Goes along with a parent. For a move, or a copy with children, a page whose selected ancestor is being moved or copied isn't handled twice. A skipped ancestor doesn't count, so its selected children are handled on their own.
• Skipped, with the reason. Examples are a move into the page's own subtree, a page that's already a direct child of the target, a copy title that would go past 255 characters, and a same-space copy with no title prefix (Confluence needs unique titles in a space).

The preview also reads your permissions in the space (or in the target page's space for move and copy) and warns you if Confluence says you can't edit, add or archive pages there. It's a warning, not a block. Confluence still decides page by page when the job runs, because page restrictions can differ.

When you start the job, the server runs the same search and plan again. If any selected page or its result differs from the preview, the job doesn't start and you're asked to preview again. That holds even when the count is the same, for example when one page drops out of a CQL date range and another comes in. Children that aren't selected aren't part of this check, so a copy with children copies the children a page has when the job runs.

Running jobs

Jobs run from the settings page of the person who started them. The page calls the app's runJobBatch resolver again and again. Each call handles up to 5 pages (it starts no new page after about 12 seconds) and saves progress after every page. These are normal user-invoked resolver calls, so every Confluence request runs as you (asUser()) with your permissions. Keep the page open while the job runs. If you close it, the job pauses where it was. Open the page again and choose "Resume job", or cancel it. A paused job stops blocking new jobs in the space after 15 minutes, and you can still resume it later if no other job has started there. Only the person who started a job can run or resume it.

The app used to run jobs in the background with Forge async events. Forge doesn't give asUser() a usable user there. On a live site every page failed with PROXY_ERR. So there's no background step any more.

The page shows a progress bar, the counts and the first 100 failures with Confluence's own error message for each. Details in the job history lists every page of a job with its result (only for the person who started it).

• Copy with children and archive start Confluence long tasks. The job waits for each task to finish (the page checks every 5 seconds, for up to about 10 minutes per task) before it moves on. A task that's still running after that is reported as a failure that may still finish, and it isn't sent again.
• Archive requests go in batches of 25. If Confluence refuses a batch, the job retries those pages one at a time so you can see which page failed. Pages the batch did archive count as done.
• If Confluence rate-limits the app, the job pauses for 30 seconds and retries the same page, up to 3 times. A copy or archive request that gets a server error isn't sent again, because Confluence may have done the work. The failure tells you to check.
• If Forge can't send a request to Confluence as you (PROXY_ERR), the page isn't counted as failed. The job retries a label or move request up to 3 times, 30 seconds apart. Then, or at once for copy and archive, it stops with a message that says so.
• If Confluence answers HTTP 410 Gone (it no longer offers an API the app uses), the job stops at the first page that gets it, with no retries. That page and the pages after it show as not processed. Every other page would get the same answer.
• Cancel stops the job before its next page. A paused job is closed at once. A copy or archive task that Confluence has already started may still finish.
• One job can run per space at a time. A job that makes no progress for 15 minutes is shown as paused and no longer blocks new jobs.
• When the job ends, a job where every page failed shows "failed" with the count, not done. A job where some pages failed shows "done" with the failed count, in yellow.

You can always see and cancel the jobs you started. Other people's jobs are listed only for space admins, and only a space admin can cancel someone else's job. The server checks this with Confluence as you each time (your space operations must include administer on the space). If Confluence doesn't confirm it, you see only your own jobs. Admins see the operation, status and counts of other people's jobs. Page titles, the target page's title and failure details are shown only to the person who started the job.

Undo for label jobs

Label jobs keep an undo log for 30 days. It records only what the job changed. A label that was already on a page before an add job isn't removed by undo, and a page that never had the label isn't touched.

The job notes each label change in the log before it sends it. If Confluence's answer gets lost (a server error after the change was made, or a batch cut off mid-request), the next attempt reads the page's labels again and logs the change if it happened. If the page fails for good, the job reads the labels once more and keeps only the changes it finds. Undo also checks each page before it changes anything, so it only reverses a label that's still in the state the job left it in. Only the person who started the job can undo it. Undo runs as a new job you can watch like any other, and if it fails or is cancelled you can run it again.

Move, copy and archive jobs can't be undone by the app. The confirmation dialog says so before you start.

Permissions

Every call to Confluence runs as the person using the app (asUser()), from resolver calls made by the open settings page. That includes the job batches. There are no background steps and no asApp() calls. The app never calls Confluence as itself. So a job can only do what that person could do by hand, and the server runs a job's batches only for the person who started it.

The app has no external permissions, no remote back end and no egress. All code runs on Atlassian's Forge platform, so it's built to qualify for Runs on Atlassian. Atlassian decides eligibility, and forge eligibility checks it after deploy.

Once a week a scheduled trigger reports the stored account IDs to Atlassian with the Forge personal data reporting API (privacy.reportPersonalData). Job records of accounts that Atlassian reports as closed lose their account ID.

PRIVACY.md lists what's stored and for how long.

Limits

Not included

• Changing page owners. I couldn't confirm a Confluence REST endpoint that changes only the owner. Updating the page itself would mean sending the whole body back and adding a page version for every page, so this version leaves it out.
• Delete. Archive is the safer option, since archived pages can be restored in Confluence.
• Blog posts, whiteboards and databases. Only pages are selected (type = page).

Known limitations

• It hasn't run on a live Confluence site yet. The logic is covered by unit tests against a fake site, and the UI Kit page was syntax and import checked but not rendered. NOTES.md has the smoke test for the first deploy.
• The job runs only while its page is open. If a batch is cut off mid-page (the tab closed, or the resolver timed out), the next batch continues from the last saved page after 30 seconds. The page that was in progress may be sent twice, which can make a second copy.
• The space admin check and the permission warnings read GET /wiki/api/v2/spaces/{id}/operations. Its live answer hasn't been checked yet. If it doesn't list administer for space admins, admins see only their own jobs and can't cancel other people's jobs. A stuck job from someone else then stops blocking new jobs after 15 minutes.
• The personal data report hasn't run against Atlassian yet. Run forge lint to see if it needs a scope, and check the trigger's log line after the first week.
• Moving pages to another space follows Confluence's move rules. A title that already exists in the target space makes that page fail with Confluence's message.

Support Zovo

Zovo builds and maintains this app. If it saves you time, you can support the work on GitHub Sponsors. Sponsorship is optional, and the tool works the same without it.

Zovo is made by theluckystrike on GitHub.

More tools by Zovo

• AskSpace. Lets people ask and answer questions inside Confluence.
• CodeBlock+. Adds code blocks with titles, line numbers and highlighted lines to Confluence.
• Code Snippets from GitHub Gists. Embeds public GitHub gists in Confluence pages with syntax highlighting.
• Issue Dates Calendar. Shows Jira issues on a calendar inside a Confluence page.

License

MIT, see LICENSE.