Best practices when using Reporting

Reporting is a powerful app for Confluence that gives great power to the user. This can be overwhelming sometimes as the vast array of features can be confusing, and knowing which feature to use that's suitable for your use case is important so that you do not tax your Confluence instance and cause performance issues.

This page documents our suggested best practices for using the powerful Reporting macros and what common mistakes to avoid.

Suggested best practices

Avoid using nested reports

While writing reports it is always a good idea to utilize single layer reports rather than multi layer (nested) reports because it is easier to execute and has better performance due to its simplicity.

Pop quiz

Which of the following two reports are a better option for getting the titles of grandchildren pages:


Avoid using the @all parameter in Content Reporter

Using the @all parameter for the Content Reporter macro is not encouraged for large Confluence instances because it will query all contents created on all spaces. This will inevitably cause huge performance issues.

As such, using the SPACE KEY (Any other space key may be specified explicitly) parameter or the @self (The space the current content is in) parameter can be used for faster reporting results.

Always keep the Match All Criteria parameter checked in Content Reporter

The Match All Criteria parameter is used to control the flow of reports based on the Content Reporter parameter values.

If it is checked (set to True) then it will report only the values which matches with all of the parameter values in that Content Reporter macro.

On the other hand, if it is unchecked (set to False) then it will attempt to report any of the parameter values. Doing so in large Confluence instances will cause huge performance issues due to Content Reporter's attempt to report large results.

Use Sort macros to have sorted results

Reporting doesn't sort results by default unless you use the page:sorted children or page:sorted descendents/descendants keys from the Page Supplier

You may not be able to use those keys all the time therefore if you desire sorted results, a good practice would be to always add a Sort macro (Boolean Sort, Natural Sort, Number SortDate Sort and Text Sort) within one of the Reporter macros (Combining Reporter, Content Reporter, Expanding Reporter, Grouping Reporter, Local Reporter, Space Reporter, User Group Reporter and User Reporter).