---
title: "Document States Report macro"
canonical: "https://support.appfire.com/space/COMALACDCLS/650122298/Document%20States%20Report%20macro"
format: markdown
---
> Macro (aura-html)

> Macro (excerpt)
> 
> Display on a page the workflow state information from content across one or more spaces, including options to filter to specific states, spaces, and named approval(s)

## Overview

The **Document States Report** **macro **renders a list of pages and blog posts and associated workflow state information.

This workflow information in the [reporting column](https://appfire.atlassian.net/wiki/spaces/COMALACDCLS/pages/650122298/Document+States+Report+macro#docstatesmacroreportcolumns)s can include

- Date and time of the last state change
- The user who actioned the last state change to the current state
- Approvals in the state and approval related information, including reviewers and decisions

One or more[ filters ](https://appfire.atlassian.net/wiki/spaces/COMALACDCLS/pages/650122298/Document+States+Report+macro#docstatesmacrofilters)can be added to the report macro, for example, workflow states, content label, parent, space(s).

Once added to a page, the report macro dynamically updates the displayed information. This is great for tracking content workflow states across multiple spaces.

## Permissions

Anyone can see this report.

- **View-only **users only see results for content that has reached a Published (** **`final=true`** **) state, even if there are subsequent draft-state edits to that content
- Documents that have not yet been published or that have an applied workflow that does not define a published state are not shown

Administrators can make all results available to everyone by changing the** **[Workflow Activity and Drafts Visibility](https://appfire.atlassian.net/wiki/spaces/COMALACDCLS/pages/649564301)** **setting.

## Adding the report

Choose the Document States Report macro to add the report to a page. In the editor:

- 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

![cdc_draftpage_adddocstatesreport.png](media://040e7235-9678-4296-b587-984712f0630a)

- Choose **Edit**

In the macro editor:

- Select report filters
- Configure display column settings

![cdcdc_documentstatesreportmacro_macroeditor.png](media://3ca257b5-327d-46f2-8c9f-008e96fb1655)

> 📝 From v2.0.4, **changed**, **updated**, **created,** and **due date** are displayed as date and time values. Periods are no longer displayed.

- Scroll down the macro editor to add or edit report filter options
  - 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:

![cdcdc_documentstatesreport_onenetry.png](media://bbc17566-0f6e-4d74-8822-b200c4659532)

Move your pointer over the report to display:

- Report dropdown menu filter button options on the page to filter the page display by **Workflow** and, or **State**
- **Data Refresh** option to open the [space Data Refresh dashboard](https://appfire.atlassian.net/wiki/spaces/COMALACDCLS/pages/649861284) to repopulate data used by reporting tools and report macros in the space [v2.1]

Depending on the chosen column, each report column heading can be used to sort the report display alphabetically or chronologically.

> ℹ️ From Comala Document Control v2.0.4, dates are displayed as 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**,** created**,** created by, **and **space **displays details of any approvals in the current workflow states.

![Screenshot 2024-04-22 at 23.48.03.png](media://80c8df43-a143-4f52-a4eb-b3b25d8062d4)

### Filter the report

In the macro editor, select options to filter the report. These include options to filter by state, space key, content label, workflow, or CQL (see table below).

## Report filters

The filters are listed alphabetically in the macro editor.

| **Setting** | **Default** | **Notes** | **Ver** |
| --- | --- | --- | --- |
| **CQL Filter** | *blank* | <span style="color: #172b4d">A comma-separated list of CQL filters - the values must be indexed.  </span><br><span style="color: #172b4d"> For CQL field references  </span><br>- [Workflow CQL Fields](https://appfire.atlassian.net/wiki/spaces/CDML/pages/650250829)
- Comala Document Management [document states report macro](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649956057)<br>> ℹ️ <span style="color: #172b4d">from </span><span style="color: #172b4d">[v1.12.6](https://appfire.atlassian.net/wiki/spaces/COMALACDCLS/pages/649861010)</span><span style="color: #172b4d">+, filters can be added using Confluence CQL format and can include </span>**OR**<span style="color: #172b4d"> and comparison operators</span><br>> 📝 <span style="color: #172b4d">Before v1.12.6, the CQL filter must be in the form </span>`FieldName:Value` |  |
| **Label** | *blank* | Should the report be filtered by content label(s)?<br>- Leave empty to include all content
- Specify one label name to filter to a specific label
- List multiple label names, separated by commas, to filter to content with any of those labels<br>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 reports pages containing any of the listed labels.* |  |
| **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<sup>☨</sup> | <sup>☨</sup> v2.0.4+ [DATA CENTER] |
| **Ancestor page** | blank | The report is limited to the descendant pages of the specified page.<br>- Use **@self** to report on the descendant pages of the current page
- Specify a page title to include only its descendant pages<br>> 📝 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] |
| **Spaces(s)** | @self | Which space(s) should be included in the report?<br>- 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)?<br>- 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* | A comma-separated list of workflows to be displayed. |  |

> 📝 The Document Approvals Report macro provides access to approval filters (approval name, assignees, approvers).  [v2.1+]

## Reporting columns

All columns except Page Title can be added or removed from the displayed report.

> ℹ️ The column entry order in the macro editor defines column order on the page.

The default column entry for the column display is 

- **title,state,changed,updated by,updated**

These can provide parity of report display when displaying state approval information.

Only the following columns are **sortable** in the report UI.

- **Title**
- **Created**
- **Due date**
- **Read Confirmation**
- **State**
- **Updated**
- **Created by**
- **Workflow**

The document states macro has two parameters to define the sorting of the report (from v2.0.4 [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 | Version |
| --- | --- | --- |
| title | Page title (always displayed) | 1.10.0+ |
| approvals | Approval(s) in the current specified state<br>- Single approval - shows assigned users
- Multiple approvals - shows each individual approval.<br>Click each approval icon to show the assigned user(s) | 1.10.0+ |
| approval status | Displayed as an approval status lozenge<br>- Approved
- Pending
- Rejected<br>If no approval is present in the current state, no approval status is displayed. | 1.10.0+ |
| approved version | The approved (final state) page version | 1.12.0+ |
| approved version approvers | The user(s) that caused the page to enter the final state | 1.12.0+ |
| approved version date | Duration since the approved (final state) was approved | 1.12.0+ |
| changed | Date and time of last approval change | 1.10.0+ |
| 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.<br>- a comment added by the user is included in the entry (from v2.3.1+) | 1.10.0+<br>2.3.1+ |
| created | Date and time of page creation | 1.12.2+ |
| created by | The user that created the page | 1.12.2+ |
| due date | Date and time of due date | 1.10.0+ |
| state | The current state of the content with the state icon | 1.10.0+ |
| space | The name of the space that the page is in | 1.12.2+ |
| updated | Date and time of last page update | 1.10.0+ |
| updated by | The user that last edited the page | 1.10.0+ |
| workflow | The workflow applied<br>> ℹ️ Although page workflows are displayed in the unfiltered report, you can only filter this column by space workflow names. There is no option to filter on-page workflow names. | 1.10.0+ |

## Exporting the page

The document states report macro is rendered when a page including the macro is exported to PDF, Word, 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.

| Report Column Entry | Export render | Version |
| --- | --- | --- |
| title | Page title with full link (including host Confluence instance name) | 2.0.5 + |
| approvals | Not displayed |  |
| approval status | Not displayed |  |
| approved version | Version number in format - <u><span style="color: #4c9aff">v1.1.0</span></u><br>- Link to the public version of the page (the last version created on the transition to the workflow final state) | 2.0.5 + |
| approved version approvers | Comment separated list of  usernames that approved the page<br>> ℹ️ Approvers are for the approval that actioned the transition to the final state | 2.0.5 + |
| approved version date | Duration since the approved (final state) was approved | 2.0.5 + |
| changed | Date in the preferred format of the user | 2.0.5 + |
| changed by | Username<br>- User who actioned the last change state change<br>> ℹ️ No link is included for the username<br>- Comment added by the user is included (from v2.3.1+) | 2.0.5 + |
| created | Date in the preferred format of the user | 2.0.5 + |
| created by | Username<br>- User who created the page<br>> ℹ️ No link is included for the username | 2.0.5 + |
| due date | Date in the preferred format of the user | 2.0.5 + |
| readack status | Status of read confirmation:<br>- Pending
- Completed | 2.0.5 + |
| state | The current state of the content<br>> ℹ️ No color or status indicator circle. | 2.0.5 + |
| space | Space name with a link | 2.0.5 + |
| updated | Date in the preferred format of the user | 2.0.5 + |
| updated by | Username<br>- User who last updated the page<br>> ℹ️ No link is included for the username | 2.0.5 + |
| workflow | Applied workflow name | 2.0.5 + |

The document states that macro filter settings are used to display the rendered report when rendering the exported table for the macro.

- Columns
- CQL filter
- Label
- Number of items to display
- Parent page
- Spaces
- States
- Workflows
- Sort
- Sort order

> 📝 If the column choice exceeds 12, the rendered table can be displayed with columns transposed as rows to ensure fit on the exported page. The export may also generate additional tables in the rendered export when there are 12 entries or more.