---
title: "Key concepts"
canonical: "https://support.appfire.com/space/RFC/477333175/Key%20concepts"
format: markdown
---
> Macro (aura-html)

<span style="color: #000000">Reporting for Confluence Cloud is a powerful app that helps you gain insights and information from your Confluence Cloud site. Reporting also allows users to create sophisticated systems using data and metadata that already exist on your Confluence sites.</span>

## <span style="color: #000000">Challenges</span>

<span style="color: #000000">Ever wondered how you can:</span>

- <span style="color: #000000">Generate a list of recently updated pages in a specific space.</span>
- <span style="color: #000000">Generate a list of all Confluence pages with a particular label.</span>
- <span style="color: #000000">Display users who have their birthday today.</span>
- <span style="color: #000000">Create a live dashboard of the status of projects and get details about them.</span>

## <span style="color: #000000">Solution</span>

<span style="color: #000000">Reporting lets you 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.</span>  
<span style="color: #000000">It all starts with understanding a few key concepts.</span>

## <span style="color: #000000">Your raw data</span>

### <span style="color: #000000">Advanced searching using Confluence Query Language (CQL)</span>

<span style="color: #000000">You have probably heard of</span> [JQL (Jira Query Language)](https://www.atlassian.com/software/jira/guides/expand-jira/jql). [CQL](https://developer.atlassian.com/server/confluence/advanced-searching-using-cql) <span style="color: #000000">is the Confluence equivalent, which lets you run advanced searches on your Confluence content. </span>

<span style="color: #000000">An advanced search lets you 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.</span>

<span style="color: #000000">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.</span>

A simple query in CQL (also known as a **clause**) consists of a* *[field](https://developer.atlassian.com/server/confluence/cql-field-reference/), <span style="color: #000000">followed by an</span> [operator](https://developer.atlassian.com/server/confluence/cql-operators-reference/), <span style="color: #000000">followed by one or more values or</span> [functions](https://developer.atlassian.com/server/confluence/cql-function-reference/). <span style="color: #000000">For example, the following simple query finds all content in the </span><span style="color: #000000">*DOCS *</span><span style="color: #000000">space. It uses the </span>`space`<span style="color: #000000"> </span>field*, *<span style="color: #000000">the</span> `EQUALS` <span style="color: #000000">operator, and the </span>`"DOCS"` value<span style="color: #000000">.)</span>

```java
space = "DOCS"
```

<span style="color: #000000">Understanding CQL and how it works is crucial for building quality reports.</span>

## <span style="color: #000000">Refining your data and drilling down within metadata</span>

### <span style="color: #000000">Expansions</span>

<span style="color: #000000">Expansions are the extra bits of information available for various content types, including pages, blogs, and spaces. 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.</span>

<span style="color: #000000">Every CQL clause can be expanded to the following items:</span>

- `history`
- `body`
- `container`
- `ancestors`
- `children`
- `descendants`
- `space`
- `version`
- `metadata`

<span style="color: #000000">These expansions can also contain more information about that specific item. For example, if you drill down and expand further on</span><span style="color: #000000">* *</span>`space`<span style="color: #000000">*,*</span><span style="color: #000000"> you can see the following values:</span>

- `space`
  - `space category`
  - `space key`
  - `space title`
  - `space type`

<span style="color: #000000">The nested structure of the expansions allows you to drill down only on the specific item, which is helpful if you are not sure what type of data is available or suitable for your use case. The Reporting app is equipped with an </span><span style="color: #000000">*Explore *</span><span style="color: #000000">view that lets you look up and locate the right information under the expansion tree.</span>

## <span style="color: #000000">Transformation</span>

<span style="color: #000000">After getting your JQL and the expansions right where you want them, 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 the Reporting app uses a mixture of technologies to transform and format JSON data into readable information. You can easily interact with </span><span style="color: #000000">*Report Builder*</span><span style="color: #000000">** **</span><span style="color: #000000">and</span><span style="color: #000000">** **</span><span style="color: #000000">*Report Blocks*</span><span style="color: #000000">** **</span><span style="color: #000000">to create your reports. The filtering feature uses JMESpath syntax to facilitate more fine-tuned results.</span>

### <span style="color: #000000">Key(s)/ Value(s)</span>

<span style="color: #000000">This is the actual value of the data or metadata in your Confluence. We refer to these data points as </span><span style="color: #000000">**Keys/ Values **</span><span style="color: #000000">in the app and our documentation.</span>

### <span style="color: #000000">Report Builder</span>

<span style="color: #000000">With the </span><span style="color: #000000">[Report Builder](https://appfire.atlassian.net/wiki/spaces/RFC/pages/477333116)</span><span style="color: #000000">, you shape your report the way you like it. </span><span style="color: #000000">*Report Builder*</span><span style="color: #000000"> 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</span><span style="color: #000000">*.*</span>

### <span style="color: #000000">Report Block(s)</span>

<span style="color: #000000">[Report Blocks](https://appfire.atlassian.net/wiki/spaces/RFC/pages/477333123)</span><span style="color: #000000"> 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 </span><span style="color: #000000">*Report Block*</span><span style="color: #000000"> generates one column of results for the table.</span>