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 features are 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 powerful Reporting macros and some common mistakes to avoid.
Suggested best practices
- 1 Avoid using nested reports
- 2 Answer
- 3 Avoid using the @all and @global parameters in Content Reporter
- 4 Always keep the Match All Criteria parameter checked in Content Reporter
- 5 Use Sort macros to have sorted results
- 6 Use filters in nested reporter macros when using Combining Reporter for more efficient queries
- 7 Scaling up users with the User Reporter macro
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 their simplicity.
Pop quiz
Which of the following two reports is a better option for getting the titles of grandchildren pages?
Answer
The answer is option A because it is simple and it does not use nested reporter macros.
Avoid using the @all and @global parameters in Content Reporter
Using the @all and @global parameters 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) the 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 match 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 Sort, Date 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).
Use filters in nested reporter macros when using Combining Reporter for more efficient queries
If you need to filter results from the Combining Reporter macro, it is best to apply filters on each of the nested reporter macros rather than having a filter on the Combining Reporter macro.
Scaling up users with the User Reporter macro
The User Reporter macro is a powerful tool that can be used to retrieve and report on Confluence users based on their space permissions, user groups, or usernames. However, as the number of users in the Confluence instance increases and as more external user directories are connected, broad usage of the macro with no filters will increasingly tax the instance’s resources. Here are some general best practice guidelines to get the best performance out of a User Reporter report:
1. Avoid using the macro without entering any parameters
Using the macro without any parameters defined means creating a user query with no filters. This has some valid use cases in smaller instances, but will surely start to noticeably impact performance for instances with more than 5,000 users.
2. Avoid using the default user group in User groups parameter
If the Confluence instance uses a default user group with all Confluence users as members such as “confluence-users”, avoid using that group in the user groups parameter. Using the default group will result in querying and reporting on all the users in the instance, which will impact the performance of instances with a large number of users.
3. Use more specific parameter values to narrow down results
When applicable, use more specific parameters such as usernames, space permissions with edit/admin instead of view, and smaller user groups instead of larger user groups. Using broader filters when not required will use up more resources when querying and the report will contain unwanted results.