ATLASSIAN HOW TO'S
Search and Replace in Confluence
When creating and updating documentation, it is often necessary to search for and replace text fragments. If, for example, a product name changes, authors need to update every single occurrence within their documentation. What if there was a way to automate this process?
Atlassian Confluence’s built-in editor features a handy search-and-replace tool. Unfortunately, it doesn’t offer a way to exchange strings on multiple pages, across spaces or throughout the entire collaboration platform – and it’s unlikely that such a feature will be added any time soon. Instead, Confluence’s product managers point us to the Atlassian Marketplace, where third-party developers can provide suitable add-ons.
In this blog post, I’ll take a closer look at one solution – available for Confluence 5 and above – that will help you search and replace Confluence content like a pro.
The ‘Search and Replace’ Add-on for Confluence
The only graphical search-and-replace solution currently available from the Atlassian Marketplace for the latest Confluence generation (5.x) is the Search and Replace add-on by Rumpelcoders.
This tool allows Confluence administrators to search and replace text on individual pages, throughout entire spaces, or globally. You can also use it to delete macros or alter macro parameter values.
Once the add-on is installed, a new menu item – Search and Replace – appears in Confluence’s global configuration.
Here’s how to use the Search and Replace tab:
- Choose the scope (the entire Confluence installation, a single space, or one page).
- Enter the text you want to replace into the Search for field, e.g. MyProduct (The text you enter may include storage format syntax).
- In Replace with, enter your desired replacement string.
- Click Show Occurrences to display a list of all the text matches in your selected scope.
- Hit Replace all to make your replacements permanent.
Visit the support page for additional options, such as the ability to replace macro parameter values or delete macros.
The add-on was first released in early December 2014, and only two versions have been released so far. As a result, there are still a few teething issues regarding data integrity/security, functionality, and usability.
- Using the add-on without due caution could harm your Confluence content:
- You might produce invalid data, because the add-on operates directly on the Confluence XML storage format. This is why the user interface warns you that you may end up jeopardizing your entire Confluence installation.
- User-defined view/edit restrictions will be ignored when replacing content. Pages could be modified, even if restrictions have been applied.
As it stands, the UI has a few limitations:
Text within page titles cannot be changed at the present.
- Special characters in your query and replacement strings must be entered in the same way as Confluence keeps them in its storage format. For example, ü is stored as ü.
- If your string contains formatting such as emphasized letters, e.g. <em>My</em>Product, the tool will be unable to find it.
In addition, the search-and-replace process isn’t entirely user-friendly:
- The search/replace tool is only available to Confluence admins. Authors or space administrators cannot access the functionality.
- In the list of matches, you cannot choose to replace individual strings only: either all matching strings are replaced, or none.
- The search function only lists the storage format strings, and does not include links to the relevant page, space etc. that would allow you to check the context.
If you can cope with its limitations, the ‘Search and Replace’ add-on is really great to replace text (or macros) across large volumes of Confluence content. To find out more about upcoming new features, why not contact the developers themselves? I’m sure they’ll welcome your feedback.
One alternative is the Confluence Command Line Interface (CLI) tool, which offers a more technical approach.
You could also choose to edit each page manually, using the Confluence editor’s built-in search-and-replace feature (Command + F). This puts you in total control, and allows you to work with the excellent Confluence editor.
Another option is to comment on, watch and vote for the JIRA issue requesting global search-and-replace functionality in Confluence. If you do, you’ll receive a notification as soon as a solution arrives in the Atlassian Marketplace.
What do you experience when using Confluence as a documentation platform? What are your main challenges? Do you need an intelligent solution that will help you manage Confluence content more efficiently?
Please leave a comment below, or drop us an email at firstname.lastname@example.org.