Skip to main content

Replace a label across content

Swap one label for another on many pages, blog posts and attachments at once, so a renamed label doesn't leave old content behind. On the Tools page, this is Replace Label.

Applies to: Script Master for Confluence Β· Cloud

For each matching item, the tool adds the new label, then removes the old one.

Before you begin​

  • Confluence permission: permission to add and remove labels on the content in scope.
  • App permission: Replace Label is available to you. It's available to all users unless an admin changed that. See Set who can use each tool.

Confluence stores labels in lowercase. The new label can use lowercase letters, numbers, hyphens and underscores, up to 255 characters.

Replace the label​

  1. Go to Apps > Script Master Tools, then select Replace Label.

  2. Under Scope, choose Whole spaces and pick the spaces, or choose Custom scope (CQL) and enter a query. With CQL, the tool ignores the spaces.

    The Replace Label scope set to Whole spaces, with two spaces picked

  3. In Label to replace, enter the old label. In New label, enter the new one. The old label matches whatever its case.

  4. Under Content types, keep on Pages, Blog posts or Attachments. At least one must be on.

  5. Select Check content. The report shows how many items carry the label, and the CQL the tool will run.

  6. Select Replace label.

Result: Label replaced says how many items changed, and lists up to 10 failures with the reason for each.

What the check tells you​

LineWhat it means
N items carry the label "old"How many items matched. Zero is a warning, not a failure.
Only the first 5,000 items are includedThe scope matched more. Narrow it and run the tool again for the rest.
The label will be replaced with "new"The lowercase label the tool writes.

What it changes​

ItemEffect
The new labelAdded to every matching item. Adding a label that's already there changes nothing.
The old labelRemoved from every matching item, after the new one is added.
Page bodies and versionsUnchanged. A label change makes no new page version.
App contentNot reached. Confluence Cloud's API can't find custom content by label.
warning

If a run stops partway, an item can keep both labels: the tool adds the new label before it removes the old one. Run the tool again on the same scope to finish those items.

Undo a run​

The tool has no undo. To reverse a run, run it again with the two labels swapped. Items that failed the first time never got the new label, so the second run leaves them alone, still carrying the old one.