---
title: "Document States Report macro"
canonical: "https://support.appfire.com/space/CDALS/649528122/Document%20States%20Report%20macro"
format: markdown
---
> Macro (aura-html)
> Macro (excerpt)
>
> Display on a page the Document Approval workflow state information from content across one or more spaces, including options to filter to specific states, spaces, parent page, label, space
## Overview
The **Document States Report macro** displays lists of content and associated workflow state information.
This workflow information in the [reporting columns](/wiki/pages/resumedraft.action?draftId=613351597#DocumentStatesReportMacro-docstatesmacroreportcolumns) can include
- date of last state change
- the user who actioned the last state change to the current state
- approvals in the state and approval information, including reviewers and decisions
One or more[ filters ](/wiki/pages/resumedraft.action?draftId=613351597#DocumentStatesReportMacro-docstatesmacrofilters)can be added to the report macro, including workflow state(s), content label
> ✅ Once added to a page, the report macro dynamically updates the displayed information. It's great for keeping track of content workflow states across multiple spaces.
## Permissions
Anyone can see this report. However, Confluence view-only users see only results for content that has reached the **Approved** (** **`final=true`** **) state, even if there have been subsequent draft state edits to that content.
Admins can make all results available to everyone by changing the global** ****[Workflow Activity and Drafts Visibility](https://appfire.atlassian.net/wiki/spaces/CDALS/pages/649822586)**** **setting.
## Adding the report
Choose the Document States Report macro to add the report to a page.
In the page editor, either
- choose **Insert **> Macro (inline-media-image)
** → Other Macros → Reporting → Document States Report **
- or type **{Document States ...** on the page and select** Document States Report**
- choose** Edit **the macro
- choose report filters and display column settings
> 📝 From v2.0.5, **changed**, **updated,** and **created** are displayed as date and time, not as a period value.
- scroll down the macro editor to add or edit report filter options
- the report columns display options by default are the comma-separated list **title,state,changed,updated by,updated**
- by default, the report displays 20 items per page
- choose **Save** to update the macro on the draft page
- select **Update** to add the report to the page
Here's how the report looks on your page.
Mouse over the report to display
- the **State** filter option for the current report
- the **Data Refresh** option to open the space [Data Refresh dashboard](https://appfire.atlassian.net/wiki/spaces/CDALS/pages/649659081) to repopulate the data used for workflow reports and report macros [v2.1]
Each report column heading can be used to sort the report display alphabetically/chronologically, depending on the chosen column.
> 📝 From Comala Document Approval v2.0.5, the report displays exact dates.
## Customizing the report
Edit the **Document States report** macro to customize the report by
- choosing the information to be displayed in each column of the report
- adding one or more filters
### Customize the displayed columns
In the macro editor, amending the listed columns to **title**,** state**,** changed**,** approval status**,** approvals**, **updated by**, **updated**,** space**, **changed, **or **changed by **displays details of approvals in each of the current workflow states.
The** title** column is always displayed.
### Filter the report
In the macro editor, select options to filter the report.
> ℹ️ Filter options include by state, space key, approval name, workflow, or CQL (see table below).
For example, add a filter on the **State **filter using the **Review** state.
The filtered report displays only the page(s) currently in the **Review** state.
## Report filters
The filters are listed alphabetically in the macro editor.
| **Setting** | **Default** | **Notes** | **Ver** |
| --- | --- | --- | --- |
| **CQL Filter** | *blank* | A comma-separated list of CQL filters - the values must be indexed.
For CQL field references
- [Workflow CQL Fields](https://appfire.atlassian.net/wiki/spaces/CDML/pages/650250829)
> ℹ️ From [v1.10.5](https://appfire.atlassian.net/wiki/spaces/CDALS/pages/649789537)+, filters can be added using Confluence CQL format and can include **OR** and comparison operators
> 📝 Before v1.10.5, the CQL filter must be in the form `FieldName:Value` | |
| **Label** | *blank* | Should the report be filtered by content label(s)?
- leave empty to include all content
- add one label name to filter the report to content with the specific label
- add multiple label names, separated by commas, to filter to content with any of those labels
If using a list of labels, you can prefix the list with ** **`&`** ** (ampersand) to require that the content has all the labels. O*therwise, it will report pages containing any of the listed labels.* | |
| **Number of items to display** | 20 | The maximum number of results to show per page. | |
| **Parent page** | *blank* | - *blank *defaults to the space home (does not include the home page in the report as this is the default parent)
- specify a title to list that page's children
- @self applies the report using the current page as the parent page☨
> ℹ️ The parent page is not included in the report. | ☨ @self from v2.0.5 [DATA CENTER] |
| **Ancestor page** | blank | The report is limited to the descendant pages of the specified page.
- use **@self** to report on the descendant pages of the current page
- specify a page title to include only its descendant pages
> 📝 If specifying an ancestor page, you cannot list multiple space keys. The report defaults to the descendant pages of the added page. | v2.4.0+ [DATA CENTER] |
| **Sort** | Title | **Sort** defines the value to sort by with the following options
- Title
- Updated
- Created
- Created by | v2.0.5 [DATA CENTER] |
| **Sort Order** | ascending | **Sort Order** defines the order of the sorting as either
- ascending
- descending | v2.0.5 [DATA CENTER] |
| **Spaces(s)** | @self | Which space(s) should be included in the report?
- default is **@self** for the current space
- list multiple [space keys](https://confluence.atlassian.com/doc/space-keys-829076188.html), separated by commas, to report on multiple spaces
- use **@all** to search all spaces | |
| **State** | *blank* | Should the report be filtered to a specific state or state(s)?
- Leave empty to report on all states
- Specify one state name to report on that state
- List multiple state names, separated by commas, to report on specific states | |
| **Workflow(s)** | *blank* | This is redundant as there is only one workflow in the Comala Document Approval app. | |
> 📝 The Document Approvals Report macro offers filters relating to approval information (approval name, approvers, assignees).
## Reporting columns> Macro (anchor)
All columns except Page Title can be added or removed from the displayed report. The macro editor's column entry order defines the page's column display order.
The default column entry for the column display is
- **title,state,changed,updated by,updated **(*no blank character spaces are required after each comma when adding a custom list of columns to display in the macro editor*)
These can provide parity of report display when displaying state approval information.
Only the following columns are **sortable** in the report UI.
- **Title**
- **Created**
- **Read Confirmation**
- **State**
- **Updated**
- **Created by**
- **Workflow**
The document states macro has two parameters to define the sorting of the report (from v2.0.5 [DATA CENTER] )
- **Sort**: defines the value to sort by with the following options
- Title
- Updated
- Created
- Created by
- **Sort Order**: defines the order of the sorting as either
- ascending
- descending
| **Report Column Entry** | **Description** | |
| --- | --- | --- |
| title | Page title (always displayed) | 1.8.0+ |
| approvals | Approval(s) in the current specified state
- Single approval - shows assigned users
- Multiple approvals - shows each approval.
Click each approval icon to show the assigned user(s) | 1.8.0+ |
| approval status | Displayed as an approval status lozenge
- Approved
- Pending
- Rejected
If no approval is present in the current state, no approval status is displayed. | 1.8.0+ |
| changed | Date and time of the last state change | 2.0.5+ |
| changed by | The user that caused the page to enter the current state. In the case of a content review with multiple approvers, this is the final approver.
- any user comment is added to the entry (from v2.3.1+) | 1.8.0+
2.3.1+ |
| created | Date and time of the page creation | 2.0.5+ |
| created by | The user that created the page | 1.10.1+ |
| space | The name of the space that the page is in | 1.10.1+ |
| state | The current state of the content with the state icon
> ℹ️ Always displayed. | 1.8.0+ |
| updated | Date and time of the last page edit
> ℹ️ Always displayed. | 2.0.5+ |
| updated by | The user that last edited the page | 1.8.0+ |
## Exporting the page
The document states report macro is rendered when a page including the macro is exported to PDF, Word, or HTML.
> 📝 The document states report is also supported when exporting a page using:
> 📝
> 📝 - [K15t Scroll PDF Exporter for Confluence Cloud](https://marketplace.atlassian.com/apps/7019/scroll-pdf-exporter-for-confluence?hosting=datacenter&tab=overview)
> 📝 - [Snapshot Publishing](https://appfire.atlassian.net/wiki/spaces/AHP/pages/650215885) feature in [Appfire Comala Publishing](https://marketplace.atlassian.com/apps/143/comala-publishing?hosting=datacenter&tab=overview)
The following columns (when included in the report macro configuration) are supported when exporting the page.
When rendering the exported table for the macro, the document states macro filter settings are used to display the rendered report
- Columns
- CQL filter
- Label
- Number of items to display
- Parent page
- Spaces
- States
- Workflows
- Sort
- Sort order
> 📝 When the column choice exceeds 12 columns, the columns are transposed as rows to ensure fit on the exported page. The export might also generate one or more tables when there are 12 entries or more.