Managing documentation in Confluence gets messy fast. Teams create hundreds of pages across multiple spaces, and important metadata like status, owners, due dates, and review cycles end up buried inside individual documents. If you have to click through ten different project briefs to check their status, you're wasting time.
The Page Properties macro combined with the Page Properties Report macro solves this by turning scattered project data into a clean, centralized dashboard. Instead of manual status updates or messy spreadsheets, you tag information at the page level and pull it automatically into a dynamic summary table.
Here's how to set up, configure, and troubleshoot Confluence page properties reports so your team can actually find the information they need.
How Page Properties Work in Confluence
The system relies on two separate macros working together. If you miss either step, your summary table stays empty.
The first piece is the Page Properties macro. You place this macro on individual source pages—like project specs, meeting logs, or policy documents. Inside the macro, you build a simple two-column table where you define key-value pairs.
For example, you might add rows for Status, Owner, Target Date, and Priority. Every time someone updates the status on that specific project page, the data updates at the source.
The second piece is the Page Properties Report macro. You place this macro on a parent page or a central dashboard. It scans specified spaces or labels, aggregates all the Page Properties macros it finds, and displays them in a single, sortable table.
If you want to understand the official syntax and macro parameters provided by Atlassian, check out the Atlassian Confluence Documentation.
Step-by-Step Setup Guide
Setting up a reporting dashboard takes about five minutes if you follow a clean structure. Here's how to build one from scratch.
Step 1: Standardize Your Source Pages
Consistency is your biggest hurdle. If one page uses "Status" and another uses "Project Status", the report macro won't group them into the same column.
- Create a template for your team to use across the space.
- Insert the Page Properties macro into the template (type
/page propertiesin the editor). - Inside the macro box, insert a standard table. Make the left column your keys (Status, Owner, Reviewer, Due Date) and leave the right column blank for users to fill in.
- Add a unique label to your template—like
project-spec—so your report macro can filter for it later.
Step 2: Build the Summary Dashboard
Once your team starts using the template, you can build the dashboard page where the report will live.
- Navigate to your team's home space or a dedicated reporting page.
- Type
/page properties reportto insert the macro. - Open the macro configuration panel.
- Select the Spaces you want the macro to search. You can select the current space or multiple spaces across your instance.
- In the Labels field, enter the exact label you assigned to your source templates (e.g.,
project-spec). - In the Columns to show field, type the exact names of the keys you used in your source tables, separated by commas (e.g.,
Status, Owner, Target Date). - Save and publish the page.
If your table is blank, double-check that your source pages are published (drafts won't appear) and that your label spelling matches exactly.
Advanced Configuration Options
Once your basic report runs smoothly, you can tweak the parameters to make the dashboard more useful for leadership and project managers.
Filtering by Creator or Parent Page
If your space contains hundreds of unrelated documents, a broad label search creates an overwhelming table. You can narrow the scope by adding a Parent Page restriction in the macro settings. This tells Confluence to only pull properties from pages that sit underneath a specific roadmap or folder in the page tree.
Sorting and Display Limits
By default, the report sorts pages alphabetically or by creation date. You can change the sort criteria in the macro browser to order items by specific metadata columns, such as sorting your Target Date column chronologically so overdue projects float to the top. You can also adjust the number of items displayed per page to keep long reports manageable.
Common Mistakes That Break Reports
Even experienced Confluence users run into frustrating bugs where reports refuse to populate. Watch out for these pitfalls:
- Mismatched Key Names: Case sensitivity matters. If one page uses
Ownerand another usesowner, Confluence creates two separate columns in your report. - Using Drafts: The report macro only indexes published pages. If a team member fills out the properties table on a new page but forgets to publish, it won't show up in the rollup.
- Nested Macros: Putting a Page Properties macro inside another macro (like an expandable section or a layout column) can occasionally break the parser in older Confluence versions. Keep the macro clean and direct on the page body.
- Overloading Single Pages: Don't put multiple Page Properties macros on a single page unless you have a specific reason. The report macro expects one primary property set per document.
Frequently Asked Questions
Why is my Page Properties Report table completely empty?
The two most common culprits are missing published status and label mismatches. Ensure your source pages are published, not saved as drafts, and verify that the label specified in the report macro matches the label on your source pages character-for-character.
Can I pull page properties across different spaces?
Yes. In the report macro configuration settings, you can select multiple spaces or even choose "All spaces" if your global permissions allow it. However, specifying individual spaces yields much faster load times.
How do I change the order of columns in the report table?
The report macro displays columns in the exact order you type them into the Columns to show parameter field. Simply edit the macro settings, rearrange your comma-separated list of keys, and save the page.
Can I export the report data into Excel or CSV?
Confluence doesn't include a direct one-click CSV export button specifically for the Page Properties Report macro, but you can easily copy the rendered table cells directly into a spreadsheet, or use third-party apps from the Atlassian Marketplace if automated data exports are required.
