Key concepts

Reporting for Confluence Cloud is a powerful app that helps you gain insights and information from your Confluence Cloud site. But Reporting offers more than just the creation of reports and tables. Reporting allows users to create sophisticated systems using data and metadata that already exist on your Confluence sites.

Challenges

Ever wondered how you would:

• Generate a list of recently updated pages in a specific space.

• Generate a list of all Confluence pages with a particular label.

• Display users, who are having their birthday today.

• Create a live dashboard of the status of projects and get details about them.

Solution

Reporting allows you to achieve all this on your Confluence instance. You can better understand how your users consume pages, track activities and changes for pages and spaces, and much more.
It all starts with understanding a few key concepts.

Your Raw Data

Advanced Searching using Confluence Query Language (CQL)

You have probably heard of JQL (Jira Query Language). CQL is the Confluence equivalent which allows you to run advanced searches on your Confluence content. 

An advanced search allows you to use structured queries to search for content in Confluence. Your search results will take the same form as the Content model returned by the Content REST API.

You have probably already used CQL without realizing it; whenever you perform a search with presets or an advanced search in Confluence's search field, it is actually using CQL.

A simple query in CQL (also known as a 'clause') consists of a  field, followed by an operator, followed by one or more values or functions. For example, the following simple query will find all content in the "DOCS" space. It uses the Space field, the EQUALS operator, and the value   "DOCS" .)

Understanding CQL and how it works is crucial for building quality reports.

Refining your data and drilling down within metadata

Expansions

Expansions are the extra bits of information available for various content types, including pages, blogs, and spaces. Now you can use the power of Reporting to enhance the context of your pages with these extra bits of information. Give your pages more context than just the words on them.

Every CQL clause can be expanded to the following items:

• history

• body

• container

• ancestors

• children

• descendants

• space

• version

• metadata

These expansions can also contain more information about that specific item. For example, if you drill down and expand further on "space", you can see the following values:

• space

  • space category

  • space key

  • space title

  • space type

The nested structure of the expansions allows you to only drill down on the specific item, which is helpful if you are not sure what type of data is available or suitable for your use case. Reporting app is equipped with an Explore view that allows you to look up and locate the right information under the expansion tree.

Transformation

After getting your JQL and the expansions right where you want, you will want to make sure that you have the proper means to transform this raw JSON-like information into a readable and actionable format. That is why Reporting app uses a mixture of technologies to transform and format JSON data into readable information. You can easily interact with Report Builder and Report Blocks to create your reports. The filtering feature uses JMESpath syntax to facilitate more fine-tuned results.

Key(s)/ Value(s)

This is the actual value of the data or metadata in your Confluence. We refer to these data points as Keys/ Values in the app and our documentation.

Report Builder

At Report Builder, you shape your report the way you like it. Report Builder serves as the frame structure for your report, containing search result blocks. You can choose different types of report blocks depending on the data format and how you want to present a specific value.

Report Block(s)

Reports Bocks are used for selecting values and adding static text which will be shown later in the report format of your choice. For example, if you want to view the report as a table, each Report Block would generate one column of results for the table. Currently, the Reporting offers the following types of report blocks:

• Basic Report Block: This is a simple way to add a new value to your report. The report block type allows you to choose a name (shown as the column header in table view) and renders the value as-is from the JSON response.

• Text Report Block: This is a more sophisticated report block that has the more advanced features below:

  • Allows you to add multiple values into a single block

  • Provides a complete text editor that allows text decorations, mixing static text and dynamic values.

• Image Report Block: This report block allows you to add images to your report or dashboard and helps you set the image width in pixels as an additional input.

• Link Report Block: This type of block, allows you to render the keys as Hyperlinks. Similar to any other link function, you can customize the address and text to display.

• Scaffolding Report Block (Beta Feature): This block allows you to add scaffold data to your report. Currently, this feature is in Beta, and the results may not be as expected.