Confluence Cleanup Assistant

Cleanup Assistant scans every accessible space, produces a Knowledge Health Score, detects fourteen classes of problem, recommends fixes, and lets administrators remediate them in bulk.

The first full scan builds the index every health check reads. It runs entirely in the background across queued events, and the dashboard shows live progress. Each phase does as much as its invocation budget allows, writes a checkpoint, queues the next event and returns — no handler assumes it can finish in one go, which is what lets a 100,000-page scan complete on a platform built around short-lived functions.

Every check is individually switchable and its severity is overridable from the Settings tab.

An hourly scheduled tick decides what is due. Work then moves through a queue: START → SPACE_PAGE → ATTACHMENT → ANALYZE → FINALIZE — enumerating spaces, indexing pages while running streaming rules, indexing files, then building the link graph, detecting duplicates and orphans, and finally scoring, summarising and recording trends.

Results land in custom entities. The Dashboard API reads them, and every read passes through the per-user permission validator before anything reaches a browser.

The workers budget themselves to 50 seconds and then checkpoint, which leaves almost no headroom against the default 55-second ceiling — so the scan and action workers run with a raised ceiling as a safety margin, not as licence to run longer. One slow Confluence call would otherwise be killed before the checkpoint was written, stranding the scan.

Who this is forConfluence administrators run scans and change settings. Space administrators and content owners can read findings and remediate what they already have permission to touch.

The app installs as two dashboards — one site-wide, one scoped to a single space — plus background machinery. Everything else on the dashboard reads the index a scan builds, so nothing is meaningful until the first scan has run.

1. Run the first full scan

   Open Apps → Cleanup Assistant. Before any scan the screen is an empty state inviting an administrator to run one. Use Full scan for the first run — Quick scan is incremental and only covers content changed since the last scan.

   The scan runs entirely in the background across queued events, checkpointing as it goes, so a site of any size completes regardless of per-invocation limits. A progress banner replaces the buttons and the page polls every eight seconds until it finishes. A scan already in flight blocks any new one.

2. Read the Overview

   A health score out of 100 with a grade band (healthy / warning / critical), headline totals — open findings, pages indexed, attachments, attachment storage, spaces — a findings-by-severity bar, and a clickable tile per category.

3. Work the Findings tab

   One category at a time, worst first, with filters for space, severity, owner, label, file type and update window, plus free-text search over titles and detail. Each finding carries what was found, why it matters, a recommendation, and the actions that apply to it.

   Anything you lack permission to see is removed before the list is returned, and the response reports how many were withheld rather than silently returning a short page.

4. Remediate — select, preview, confirm, execute

   Nothing mutates without a preview. Select findings or targets, then Preview: the server resolves the exact target set, removes anything you cannot act on (with a reason for each), describes the effects, and returns a signed token tied to that specific set.

   For permanent actions you then type DELETE to confirm. The token is redeemed once. Small batches run inline; larger ones move to a queue and the UI polls for progress.

   Partial failure is normal and reported. Deleting 200 pages where three fail deletes 197 and tells you which three failed and why — aborting the batch would leave the site in a state nobody chose.

5. Tune thresholds in Settings

   What counts as stale, how similar is a duplicate, what size is a large attachment, scan cadence and hour, notification rules, report schedule and formats, action safety switches, retention windows, and standing ignore rules.

   Validation is strict and server-side: a bad threshold is rejected at save time with every problem listed at once, rather than surfacing hours later inside a background scan.

6. Set a cadence and leave it running

   Defaults are a monthly full scan and a daily incremental. An hourly trigger decides what is actually due — a single tick rather than several schedules, because Forge offers only hour/day/week intervals at a time of its choosing. Deciding in code buys an administrator-chosen hour, monthly cadence, and a catch-up run if the platform skipped a tick.

The write and delete scopes exist for remediation only. Nothing is written during a scan, and every mutation runs as the calling user rather than as the app, so Confluence independently enforces whether they may perform it.

Page bodies are never stored — only measurements derived from them. Note that the index deliberately contains content most users cannot see, including page titles, which are themselves sensitive on a restricted page. That is why nothing from the index reaches a browser unfiltered.

• Not yet validated against a live Confluence tenant. Everything verifiable offline has been verified; behaviour against real Confluence API responses is the remaining unproven area, and the operations guide lists what to watch on the first run, ordered by what is most likely to break.
• Registering the app creates development, staging and production environments. Storage is not shared between them — each needs its own first scan.
• The first full scan is the expensive one; it builds the index that every subsequent health check reads.

Version history for Confluence Cleanup Assistant. The most recent release is listed first.

1. v1.0.0 Current

   Initial release.

   What it does

   • Fourteen health checks across broken links, empty and duplicate content, orphans, stale pages, attachment bloat, missing labels and owners, invalid macros, unused attachments, restricted pages, archived content, and inactive or oversized spaces.
   • A Knowledge Health Score with daily trend points and storage analytics.
   • Bulk remediation with a preview step, executed as the calling user, with a full audit trail.
   • Label and owner recommendation engines.
   • Report export to CSV, XLSX, PDF and ZIP, filtered through the same per-user permission validator as the dashboard.
   • A global page and a space page, both backed by the same Dashboard API.

   Architecture

   • A queue-driven, checkpointed scan that scales to 100,000+ pages by never assuming a handler can finish in one invocation.
   • Findings keyed by fingerprint rather than by time, so an administrator’s “ignore” decision survives a re-scan.
   • Custom entities with secondary indexes chosen from the actual query patterns — every index declared is one the dashboard or rule engine really queries, enforced by an offline manifest check in both directions.
   • No runtime dependencies beyond the Forge SDK; the XLSX, PDF and ZIP writers are implemented directly against their file formats.