Turning Confluence Pages Into Queryable Data With Page Properties

The Gap Between Narrative and Structured Data

Engineering teams often maintain service catalogs, runbooks, or RFCs in Confluence because the narrative context—the "why" and "how"—is critical. However, the structured metadata (like service owners, SLO targets, or criticality tiers) usually ends up in a separate spreadsheet to make it searchable or reportable. This creates a synchronization nightmare: the Confluence page is updated, but the spreadsheet is forgotten.

The useful takeaway is that you can treat Confluence pages as lightweight database records using the Page Properties and Page Properties Report macros. This allows you to keep the narrative and the metadata in one place while generating a dynamic, queryable dashboard without external tooling.

Mechanics of Page Properties

The Page Properties macro acts as a metadata container. When you place this macro on a page, any two-column table inside it is treated as a set of key-value pairs. For example, a left column containing "Owner" and a right column containing "Platform Team" creates a property that Confluence can index.

The Page Properties Report macro is the query engine. It scans a defined scope—such as a specific space, a set of labels, or a page hierarchy—and aggregates the properties from every page that contains a Page Properties macro. It then renders these as a consolidated table.

The Importance of Key Standardization

The report macro relies on exact string matching. Property keys are case-sensitive; if one page uses "Owner" and another uses "owner", the report will treat them as two distinct columns or silently omit the mismatched value. Because there is no schema validation, the engineering decision isn't just to use the macro, but to standardize the keys used across the entire space.

Worked Example: A Dynamic Service Catalog

To implement a service catalog, first define a standard set of keys: Service Name, Owner, Tier, and SLO Target.

On an individual service page (e.g., "Payments API"), insert the Page Properties macro at the bottom of the page. Inside the macro, create the following table:

To aggregate this data, create a "Service Index" page and insert the Page Properties Report macro. Configure the macro with these settings:

• Labels: service-catalog (ensure all service pages have this label)
• Columns to show: Service Name, Owner, Tier, SLO Target
• Sort by: Tier

The result is a live table that updates automatically whenever a service page is edited, eliminating the need for a manual spreadsheet.

Scaling via Templates and Blueprints

Manual entry leads to drift. To prevent typos and missing keys, the most durable approach is to enforce the structure via a Confluence Template or Blueprint. By providing a pre-filled Page Properties table in the template, you ensure every new service page adheres to the required schema.

For larger organizations, restrict template editing permissions to a few owners and document the "allowed keys" in the space directory. This transforms the documentation from a collection of loose pages into a structured data source that is safer to automate or audit.

Trade-offs and Limitations

Permission-Based Visibility: The Page Properties Report respects page-level permissions. If a user does not have access to a specific service page, that row will be missing from their view of the report. This can lead to inconsistent row counts between different users.

Performance Overhead: Large report scopes (scanning hundreds of pages) can degrade page load times. The macro must expand and render the content of each source page to build the table, which can cause latency on high-traffic index pages.

Silent Failures: There are no error messages for misspelled keys. If a contributor changes "Owner" to "Lead", the data simply vanishes from the report without notification.

Verification Steps

To verify the implementation in your environment:

1. Test Aggregation: Create two pages with the service-catalog label and identical Page Properties keys. Confirm both appear in the Page Properties Report.
2. Verify Permissions: View the report as a user with restricted access to one of the source pages to confirm the row is hidden.
3. Check Case Sensitivity: Create a page with a lowercase key (e.g., "owner") and confirm it does not appear in a report configured for "Owner".