Replacewell for Confluence: documentation

Replacewell finds and replaces text and links across many Confluence pages at once. You always see every match before anything changes, each changed page gets one new version, and you can undo a whole job.

Where to find it

• Apps > Replacewell find and replace: the full app, for any space you can see.
• Find and replace in a space's sidebar: starts with that space selected.
• Find and replace in this page tree in a page's "..." menu: starts with that page and everything under it.
• Confluence administration > Apps > Replacewell find and replace: settings and the audit log (Confluence admins).

Run a find and replace

1. Find: the text to look for. Replace with: the new text. Leave it empty to delete what you find.
2. Options
   • Match case: "Acme" does not find "acme".
   • Whole words only: "cat" does not find "category".
   • Regular expression: JavaScript-style patterns. In the replacement, $1, $2 insert groups, $<name> a named group, $& the whole match and $$ a dollar sign.
   • Keep capitalization: each match keeps its own capitalization, so replacing "cat" with "dog" turns "Cat" into "Dog" and "CAT" into "DOG".
   • Curly and straight quotes match (on by default): ' and ’, " and “ ”, non-breaking spaces and hyphens match their plain versions.
3. Search in: page titles and page text are on by default. Turn on Text of links, Link addresses (URLs) (links on text and smart links) or Code and code blocks when you need them.
4. Where: a whole space (tick Include blog posts if you want those too), a page and everything under it, or the pages a CQL query finds (for example space = DOCS and label = "pricing"; leave out ORDER BY).
5. Press Preview matches. Replacewell reads every page in scope and lists each page with matches. Nothing has changed yet.

Review the preview

• Each match shows the words before and after it, the text found and what it becomes.
• Untick a match to keep it as it is. Untick Include on a page to leave the whole page alone. Untick all pages and Tick all pages help when you only want a few.
• Change the Version message if you like. It appears in each page's history.
• Press Replace and confirm. The job runs in the background; you can close the page.

What Replacewell never changes

• Macro settings (for example a Table of Contents title or an Excerpt name), mentions, emoji, dates, status labels, images and files.
• Link text and link addresses, unless you turned those on.
• Code, unless you turned it on.
• Formatting: a match keeps the formatting of the text where it starts. Text split by formatting, like "Acme Corp", is still found.
• A match never runs into or out of a link, a mention or a line break.

Text inside macros that hold page content (like Excerpt or Expand) is ordinary page text and is searched.

After the replace

• Changed: one new version, with your message, written as you.
• Edited since preview: someone changed the page after your preview. Replacewell left it alone so their work isn't overwritten. Run a new search to include it.
• Nothing to change: after your unticks there was nothing left to replace, so no version was added.
• No edit permission: you can't edit that page, so it was left alone.
• Failed: Confluence refused the change (for example a new title that another page in the space already has). The reason is listed.

Tick Only pages that need attention to see just the pages that were skipped or failed. Show report (CSV) lists every page with versions before and after.

Undo a job

Open the job from My jobs and press Undo this job. Every page the job changed goes back to its content and title from before the job, as a new version. If someone edited a page after the replace, Undo leaves it alone (so their edit is kept) and lists it; you can restore that page from its page history. Undo works even if the subscription has ended.

Big jobs

• Replace and Undo run in Atlassian's background queue with a checkpoint after every page. If something interrupts them, they carry on where they stopped, by themselves within the hour, or straight away when you press Resume.
• Stop ends a running job after the current page. Pages already changed stay changed; you can still undo them.
• A search covers up to the limit your admin set (2,000 pages unless changed, at most 10,000).
• Each person can run up to 3 replace or undo jobs at the same time.

For Confluence admins

• Spaces where people can use Replacewell: leave empty for every space, or list space keys to limit it. Searches outside those spaces are refused, and pages from other spaces are skipped in CQL searches.
• Most pages one search may cover: 1 to 10,000.
• Default version message.
• Audit log: every job on the site, who ran it, what it searched for and where, the options, and how many pages it changed and undid, with each step's time. Export it as CSV. Jobs are kept for one year; page-level details for 180 days.

People can never change a page they couldn't edit themselves: the preview reads pages as the person, and the replace writes as them too.

Privacy

Replacewell runs entirely on Atlassian's Forge platform. It stores jobs and the audit log in your site's Forge storage and sends nothing anywhere else. See the privacy policy for details.

Support

Great Work support portal or hello@greatwork.company. Include the job's date (or its CSV report), what you expected and a screenshot. Never send passwords or API tokens.