Build a Lightweight ADR Register in Confluence with Page Properties

Problem: Decisions Scattered Across Chat and Email

Architecture decisions often live in Slack threads, email, or personal notes. When a new engineer asks why a database was chosen or why an API was deprecated, nobody can find the record. Confluence can solve this without adding a database or third-party app.

Thesis: Use Built-in Macros and Labels as the Register

Treat each Architecture Decision Record (ADR) as a Confluence page. Give it a label such as adr, store structured fields in a Page Properties macro, and aggregate every decision on an index page with a Page Properties Report macro. Because the data lives on versioned, permissioned pages, you get history and access control for free.

Create the ADR Page Template

Create a page template or blueprint with these elements:

• Page Properties macro with columns: Status, Date, Owner, Decision
• A section below the table for context, options considered, and consequences
• Automatic label adr on page creation, if your template supports it

Page Properties does not enforce required fields or valid values, so the template is your schema guardrail. Reviewers should check that Status uses consistent values such as proposed, accepted, or deprecated.

Build the Decision Index Page

Create a page named Decision Index. Insert a Page Properties Report macro and configure it:

1. Label filter: adr
2. Scope: Current Space or a dedicated ADR space
3. Columns: Page Title, Status, Date, Owner
4. Sort by Status so proposed decisions appear at the top

The report reads the key/value table from every page labeled adr and renders one sortable table. When you change a property on an ADR page, the index updates on the next page view.

Find Stale Decisions with CQL and REST

Use Confluence Query Language (CQL) to find decisions that have not been reviewed in six months. In the Confluence search bar, enter:

label = "adr" AND lastmodified < now("-180d")

For automation, call the content-search REST resource. Run this where your Confluence instance is reachable, replacing /wiki with your context path if needed:

GET /wiki/rest/api/content/search?cql=label%20=%20%22adr%22%20AND%20lastmodified%20%3C%20now(%22-180d%22)&limit=25&start=0
Authorization: Basic <base64-encoded-credentials>

The response returns a page of results and a next link when more pages exist. Follow the next link until it disappears. Do not assume one response contains every result. Keep expand minimal to avoid large payloads.

Permissions and Deployment Differences

• CQL and REST results respect permissions. Run governance queries as an account that can read all ADR spaces.
• Cloud and Data Center differ in macro availability, indexed fields, and REST response shapes. Confirm field names such as size versus totalSize on your deployment.
• Do not scrape rendered HTML. Use macros and the REST API as stable interfaces.

Trade-offs and Limitations

• No enforced schema: Page Properties stores data but does not validate required keys. Pair it with a template or blueprint.
• Performance: Large spaces can make the report macro slow. Scope by label and space, and avoid broad free-text queries.
• Pagination: The REST API is paginated. Scripts must loop with limit and start or follow the next link.

Actionable Closing Steps

1. Create an ADR page template with the Page Properties macro and the adr label.
2. Create three ADR pages using the template.
3. Insert a Page Properties Report on an index page, filter by label adr, and verify the table renders.
4. Run the CQL expression in Confluence search and compare results to your test pages.
5. Call content-search with limit=25 and start=0, then follow next until it is absent.
6. Schedule a monthly query that emails stale decisions to the architecture team.

This approach keeps decisions next to design docs, uses only supported Confluence features, and avoids the overhead of a separate decision database.