Introduction

Reporting is a powerful add-on that gives unlimited potential to your Confluence instance.

To truly understand Reporting, one must know the concepts that allow data to be reported on a Confluence page.

Basic Concepts

Report Structure

Each report is built up using three key sections. The results are then framed with another macro that does the primary formatting for the results. Currently, the options are Report Block, Report Table, and Report List.

Let's look at a typical example of a report:

Open

Keys and Suppliers

Macros used in the "reporters" and the report body generally makes use of Suppliers for Reporting to retrieve information.

Given a Key, a specified supplier will return an object. A supplier is referenced by its Prefix.

Example

In the above example, page is the Prefix and children is the Key.

This reporter will thus return a list of Page objects that are children of the current page.

Reporters tend to use suppliers to filter information

The report body will also use the suppliers to retrieve more detailed information. In the above example, the reporter has pulled in a list of Page objects into the report. These objects can now have their values accessed by either the Page or Content Suppliers in the body.

For example, the Content Supplier is used (with the Prefix content and title as the Key) to extract the title of the pages in the first screenshot.

Report body macros tend to retrieve information from suppliers

Always keep note of the type of object your report is returning. This is of immense help when trying to understand which Suppliers to use both in your report and in your Key-value chains. There is a supplier for every return type, even text, and lists.

The Supplier documentation will provide you with the return type of every Key and the link to its supplier documentation.

The Content Supplier can be used with all Confluence data types e.g., pages, blog posts, attachments, and comments. It provides common information about any of these objects. To get more type-specific information you will need to use the specific supplier.

Report Context

Each reporter will provide a "context" for the report results via its Key-value chain. This is the domain from which the report body can retrieve data. In the example in the previous section, the "context" was the current page's children. The report can then only access information from the current page's children.

Contexts can get more complicated when combining the results of more than one reporter, grouping them, or expanding upon other reporters.

Some contexts are more subtle and worth noting.

In general, reporters will be able to directly create the context within their designated types

You will find that all reporters will follow this naming convention: <type>-reporter e.g. Content Reporter. Each reporter can only access data within that type directly. For example, the Space Reporter cannot return information about page creators but can return information about space creators.

The Local Reporter is a special case reporter, where the context is the current page by default and filtered by you

The Local Reporter is the only reporter that allows you to provide a key-value chain as the context, with a catch: your context needs to be within the default context, which is the current page, or the page you indicate is the source.

With some trickery using the Suppliers, it is possible to expand the context of the Local Reporter, for example using the prefix: key page:children will expand the reporter across all child pages of the current page (as seen in previous examples).

Advanced Concepts

Keychains

Keychains are linked chains of prefix:key values. They are linked using the character ">". For more information on how to use these, see Supplier Keychains.

Injection

Parameter injection is supported by some report body macros and allows you to "inject" values from a supplier as a parameter into a macro. For more information on how to use this feature, see Parameter Injection.

Other Reports

It is possible in certain contexts and with certain outcomes to create "shortcut" reports that don't require the full structure of a report. For example, Report Info could be used directly outside of a report to provide information on the current page.

Example

The above displays the following:

Report On can also be used similarly to expand on an object available on the current page.

Using Reporting in Conjunction with Scaffolding

The Scaffolding add-on provides a Scaffold Supplier which allows the Reporting Plugin to access data from Scaffold fields. This combination of features has been used in many ways by users, not least in the following:

• Allowing users to enter metadata on a page and generate a report elsewhere in the site based on the metadata

• Providing users a structured way to enter information into the wiki and then collating this data elsewhere using Reporting