The Replace Macro in Bulk feature lets Confluence administrators replace specific macros across multiple pages simultaneously. This is ideal for updating macro parameters or replacing outdated macros in bulk.

1. Configure Scan Conditions

1.1. Select Scan Mode

Choose how the pages should be scanned. Note that some native macros (e.g., info, warning) are not searchable via Atlassian’s Search REST API, so they require full-page scanning.

Scan Mode	Description

Scan Mode	Description
Search pages	Scans only pages that contain specified macros. Fast, but not compatible with certain native macros.
Scan all pages	Scans all pages in the selected spaces. Required for macros like `info`, `warning`, etc.

1.2. Define Macro Settings

Specify the macro to insert, along with its parameters and position.

Field	Description

Field	Description
Old macro name	Name of the macro to be replaced, as shown in View Storage Format. You can find this via More → Advanced Details → View Storage Format on a Confluence page.
New macro name	Use the macro name as it appears in the storage format.
New macro parameters	Input parameters in XML storage format. Example: `<ac:parameter ac:name="parameter-name">parameter-value</ac:parameter>` ✅ Supported Variables: - `${oldMacro.parameters}`: Inserts all original parameters (with `<ac:parameter>` tags) - `${oldMacro.parameters.para1.value}`: Inserts the value of parameter `para1` only (no tags)
New macro rich text	Optional rich text content, supported only by some macros. Example: `<ac:rich-text-body>rich-text-value</ac:rich-text-body>` ✅ Supported Variables: - `${oldMacro.body}`: Inserts full original body (with `<ac:rich-text-body>` tag) - `${oldMacro.body.value}`: Inserts body content only (no tags)

Use variables to preserve or adapt original macro data during replacement.

1.3. Import Existing Macro

You can import the configuration from an existing macro on a page to quickly populate the macro fields.

1.4. Define Target Scope

Choose which pages to include in the scan.

Field	Description

Field	Description
Target spaces	The Confluence spaces where the macro will be added.
Content type	Choose to scan pages, blog posts, or both.
Filter by labels	(Optional) Include only pages with any of the selected labels.

2. Run Bulk Operation

2.1. Preview Scan Results

Click Start Scan to preview the list of pages that match your criteria.

2.2. Start Task

Click Replace Macros to run the bulk operation. A background task will be created—you may stay on the page or leave safely while it runs.

3. Best Practices & Tips

Always test in a staging or test space before applying changes to production spaces.
Use Scan All Pages mode when inserting native macros like info or warning which cannot be found via the Search API.
You can find macro name and parameters from storage view of the page via More → Advanced Details → View Storage Format on a Confluence page.
You can mainten a page to contain some frequently used macros. You can use Import Existing Macro to search this page and select an existing macro from this page so that the parameters can be populated automatically into the fields.