This site has moved to the integrated Appfire documentation and information site for our apps.

From February 2024 this site is no longer updated.

Take a look here! If you have any questions please email

Document States Report Macro


The Document States Report is used to display lists of content and associated workflow state information.

This workflow information in the reporting columns can include

  • time elapsed since 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 can be added to the document states report macro, for example, to limit the display of workflow information to states with one or more named approvals in the state and the current approval status.

Once added to a page, the report macro will dynamically update the displayed information. It's great for keeping track of content workflow states across multiple spaces.


Anyone can see this report but information displayed may be filtered by the user permissions for the content and the workflow state.

View-only users will only see results for content that has reached a Published ( final=true ) state, even if there are subsequent draft state edits to that content. Content that has not yet been published, or content under a workflow that does not define a published state, will not be shown.

Admins can make all results available to everyone by changing the Workflow Activity and Drafts Visibility setting.

Adding the report

To add the report to a page choose the Document States Report macro either by

  • using the macro editor on the draft page by choose Insert  → Other Macros → Reporting → Document States Report

  • or on the draft page type {Document States ... and select Document States Report

Publish the page to view the default report.

The default report displays workflow state information for content with an applied workflow (or history of an applied workflow) in the current space.

Editing the macro

  • On the draft page choose Edit the macro


  • Choose report filters and display column settings

    • scroll down the macro editor to add/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

  • Choose Update to add the report to the page

Here's how the report looks on your page.

Mouse over the report to display the report dropdown menu button options to filter the page display by Workflow and/or State.

The displayed report can also be sorted alphabetically/chronologically on a selected column.

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 titlestate, changedapproval status, approvals,updated byupdated displays details of any approvals in each of the current workflow states.

If there are multiple approvals in a state, scroll over the approval icon to display the approval name and any users assigned as approvers.

Filter the report

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

For example, add a filter on the Approval name filter using QA Review

The filtered report displays only the page(s) with the named QA Review approval.

The report macro can also filter approvals on approval status and approval assignee.

If a workflow has been removed from content that is in the scope of the report macro, but the history has been retained, the report will show the last state information for the content.

Report filters

The filters are listed alphabetically in the macro editor.









Approval assigned to


The user assigned to an approval.


  • all (default - field left blank)

  • username - approvals  assigned to the specified user

  • @self  - approvals assigned    to the current user


Approval name


Name of the approval


Approval status


Only applies if an Approval name filter is specified. Filters by approval status from dropdown menu options.

  • all (blank)

  • Approved

  • Pending

  • Rejected


CQL Filter


A comma-separated list of CQL filters - the values must be indexed.

For versions v6.16.7+ the CQL format is Fieldname1=Value 1, FieldName2=Value2

For versions prior to v.6.16.7 filter must be added in the form  FieldName1:Value1, FieldName2:Value2

For CQL field references 

The only workflow CQL searchable fields are those listed in the Comala Document Management CQL Rest API page and Atlassian Confluence CQL fields.




Should the report be filtered by content label(s)?

  • leave empty to include all content

  • specify one label name to filter to that label

  • list 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 content has all the labels. Otherwise, it will report pages containing any of the listed labels.


Number of items to display


The maximum number of results to show per page

  • max is 200


Parent page


  • leave empty to set parent page as home page for the space

  • specify a page title to filter to its child pages

The report does not include the parent page.




The comma-separated list of space keys to filter.

  • default is @self for current space

  • list multiple space keys, separated by commas, to report on multiple spaces

  • use @all to search all spaces

Specifying more than one space or all spaces disables live filtering.




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



A comma-separated list of workflows to be displayed.


Reporting columns

All columns except Page Title can be added or removed from the displayed report. The column display order on the page is defined by the order of entry of the column in the macro editor.

The default column entry for the column display is 

  •  title,state,changed,updated by,updated

These can be used to provide parity of report display when choosing to display state approval information.

The following columns are sortable in the UI of the report (from v6.16.6+)

  • Title

  • Created

  • Due date

  • Read Confirmation

  • State

  • Updated

  • Created by

  • Workflow

Report Column Entry



Report Column Entry




Page title (always displayed)

6.13 +


Approval(s) in the current specified state

  • Single approval - shows assigned users

  • Multiple approvals - click the icon to see the assigned users for each separate approval

Click each approval icon to show the assigned user(s)

6.13 +

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

6.13 +

approved version

The approved (final state) page version 

6.16 +

approved version approvers

The user(s) that caused the page to enter the final state

6.16 +

approved version date

Duration since the approved (final state) was approved

6.16 +


Duration since the last state change

6.13 +

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

6.13 +


Duration since page creation

6.16 +

created by

The user that created the page

6.16 +

due date

Duration until state expiry

6.16 +

readack status

Status of read confirmation:

  • Pending - One or more assigned read confirmations have not been completed 

  • Completed - All assigned read confirmations have been completed

6.16 +


The current state of the content with state icon

6.13 +


The name of the space that the page is in

6.16 +


Duration since last page edit

6.13 +

updated by

The user that last edited the page

6.13 +


The workflow applied

 Although page workflows will be displayed in the unfiltered report you can only filter this column on space workflow names. There is no option to filter on page workflow names.

6.16 +

For the CQL alias for each column item please see the document states report macro page.

All examples