Tips & Best Practices - Reports, Charts, Templates, CQL & Export for Confluence Documentation

Non-obvious tips that save time and prevent common configuration mistakes.

CQL Queries

Test CQL in the Confluence search bar first. Go to Confluence → Search → switch to Advanced search → enter your CQL. If it returns the right results there, it will work in the macro.
Use now("-Nd") for rolling time windows. lastmodified < now("-90d") always means "90 days ago from now" - no hardcoded dates that become stale.
Spaces mode is for quick setup; CQL is for precision. Spaces mode pulls everything in a space. CQL lets you filter by content type, date, label, title, and more. Switch to CQL as soon as you need more than one filter condition.

Only load the expansions you actually use. Each expansion group adds API call overhead. Loading all expansions when you only need version.when slows down the report.
Use the Explore panel to find field paths. Click Explore in the Center Panel to browse all available fields with sample values. Copy the exact path (e.g., version.by.displayName) into your column Data Value. This is faster than guessing.
Use Raw View when a column shows blank. Right Panel → Raw tab → search for the field name. If it's missing in the raw JSON, the expansion isn't loaded or the field doesn't exist for that content type.

Apply a template first, then customise. Templates pre-configure source, expansions, columns, and filters. Start from a template baseline and adjust - faster than starting blank.
Unlock a template before editing. Templates are locked by default. Click the Edit (lock) icon in the Center Panel to unlock. Unlocked templates become custom reports and won't receive future template updates.

Raise Result Limit before exporting. The default is 50. Set it to 500 or 1000 before clicking Export → CSV to get a full data set.
JSON export contains ALL fields, not just your configured columns. This is useful for discovering new fields or passing the raw data to a developer for processing.
Share report configurations as JSON recipes. Right Panel → Import tab → Copy JSON. Share the recipe on a "Report Library" page - teammates paste it into the macro editor to recreate the exact same report in seconds.

Set a sensible Result Limit. Loading 10,000 pages on every page view creates unnecessary load. Use filters to narrow results, then set the limit to match the filtered count.
Use Chart view for large datasets. A bar chart summarising 5,000 pages by author loads faster and communicates more clearly than a 5,000-row table.