Short answer. For the count, a Confluence admin opens Settings → Data management → Macro usage: it lists every app, the names of its macros and how many content items use each. For the list of pages, run the CQL query type = page AND macro = "macro-name" through the REST search endpoint, adding AND space = KEY to narrow it to one space. Use the macro name exactly as the Macro usage report shows it. For apps built on Forge that name is the module key, and anything else returns zero.
1. The Macro usage report: how many
The report sits in Confluence administration under Data management, at /wiki/admin/macro-usage. It has two parts.
-
All macros lists each app, bundled or installed, with its macro names and the number of content items that contain them. On our test site it showed our own Forge app as
clickable-svg(9), which matched the nine pages we knew had it. - Unused macros lists macros from installed apps that appear nowhere. The report itself says what this is for: checking that an app is not used before you disable or remove it.
Three limits, the first two stated on the report page itself. It only counts content you are allowed to see, so pages with restrictions you are not part of are missing from the numbers. Archived spaces are left out. And on our site it gave counts per macro, not links to the pages, with no space filter or export; an admin on the community forum described the same when trying to count one macro in one space. For the page list you need search.
2. CQL: which pages
type = page AND macro = "drawio"
type = page AND macro = "drawio" AND space = DEV
type = page AND macro IN ("drawio", "gliffy")
The quickest way to run it is in a browser where you are logged in: https://your-site.atlassian.net/wiki/rest/api/content/search?cql= followed by the query. The response is JSON; totalSize is the count and each result has the page title and link. It returns pages, not macros: a page with five old diagrams is one result, which matters when you estimate how much replacing is left. Change type = page to type IN (page, blogpost) if blogs use the macro too.
Four cases where the result is zero and should not be
macroName: in the search box
Many answers, including old Atlassian pages, suggest typing macroName:drawio into search. That is Data Center syntax. In Cloud it is treated as ordinary text: on our site it returned files with "drawio" in their names and not the page that actually had the draw.io macro. Use the CQL macro field instead.
A Forge app's macro under its full key
In the page storage format a Forge macro carries a key like <app-id>/<environment-id>/static/<module-key>. CQL matches only the module key, the part after static/. With our own Forge macro on nine pages, macro = "clickable-svg" found all nine; the full key and the app ID returned zero, with no error. The module key is also what the Macro usage report shows, so copy it from there. Vendors choose module keys themselves, so two apps can share one; open a couple of results to be sure.
Info, note, tip and warning panels
These used to be four separate macros, and the old names still appear in the storage format. In Cloud they are stored as one native panel element. On a fresh test page with an info panel, macro = "info" returned nothing and macro = "panel" found it, together with every other coloured panel on the site. The Macro usage report goes the same way: on our site it listed info, note, tip and warning under Unused macros while info and warning panels were in use. These macros ship with Confluence, so you will not uninstall them, but it shows that an "unused" verdict is only as good as the names behind it.
Status lozenges and code blocks
Same story, without a workaround in CQL. On the same test page macro = "status" and macro = "code" both returned zero while the page had both elements; toc and expand on that page were found within seconds. We did not find a CQL condition that lists pages with a status or a code block.
A ten-minute check before you uninstall
- Open Macro usage and write down the app's macro names and counts.
- For each macro, run the CQL query and compare
totalSizewith the count. A large gap means restricted pages you cannot see, archived spaces, or a wrong name. - Ask someone with access to restricted content to run the same query, or check with your space admins, before you rely on a zero.
- Only then disable the app, and leave it disabled for a week or two before you uninstall it, so anyone who finds a broken page can tell you while it is still easy to switch back.
For the wider audit of apps that run on Connect, see what a Confluence admin actually has before Connect end of life, and the CQL cheat sheet for the rest of the query syntax.
Disclosure: I build Forge replacements for three Connect-era apps: SVG out, Table Exporter and CQL Search. The pages behind those links explain what each old app did and what to use instead, ours included. Finding the pages, as described above, needs nothing but Confluence itself.
Frequently asked
How do I find all pages that use a macro?
type = page AND macro = "macro-name" in CQL, with the name taken from the Macro usage report.
Does macroName: work in Confluence Cloud?
No. It is Data Center syntax; in Cloud it searches for the words as text.
Why does CQL return nothing for a Forge app?
You probably used the full extension key or the app name. Use the module key, the part after static/.
Can I find pages with info panels or status lozenges?
Panels yes, all colours together, with macro = "panel". Status and code blocks, not with CQL as far as we could find.
Related: Connect app end of life, Confluence CQL cheat sheet, and what to check before installing a Confluence app.
Top comments (0)