Document States Report Macro

Overview

The Document States Report Macro displays pages and blog posts with an applied workflow and associated workflow state information. The displayed report includes live filter options to display pages by workflow and the workflow state.

Document States Report

The report macro is configured in the macro editor to

choose the displayed report columns
add report filters

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.

From v7.3.0, use the Document Approvals Report Macro to display approvals in the state and approval information including reviewers and decisions. Approval information and filters for the approval name, approval status, and approval assignees are available in the document approvals report macro.

Permissions

Anyone can see the report, but the information displayed is filtered by the user permissions for the pages and the workflow state.

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 page. A page that has not yet been published, or a page with an applied workflow that does not define a published state, are 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.

From v7.2.1 DATA CENTER the document states report displays a date value as an exact date only.

Moving the cursor over the report on the page displays an option to Refresh Data for the report From v7.3.0

Choosing this option opens the space tools Refresh Data dashboard. This option refreshes the workflow properties data used by in-app reports and report macros. This option is displayed in the macro editor by moving the cursor over the report preview.

Editing the macro

On the draft page

choose Edit the macro

In the macro editor to configure the report display. By default

columns displayed are the comma-separated list title, state, changed, updated by, updated
the report displays 20 items per page
sort order of report is descending on the page Title column

scroll down the macro editor to add/edit report filter options
- CQL filter
- label
- parent page
- states
- space(s)
- workflow(s)
choose Save to update the macro on the draft page
choose Publish or Update to add the report to the page

Here's how the default 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 title, state, changed

Displays the page, the current state, and the date of last state change.

Columns in the report can also be configured to display state approval information, for example

approvals
approval status
approved version approvers
approved version date

This displays the following report on the published page.

Filter the report

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

For example, add a filter on the State filter using Draft

The filtered report displays only the page(s) currently in the named state, Draft.

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

Report filters

The filters are listed alphabetically in the macro editor.

Setting	Default	Notes
CQL Filter	blank	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 CQL field references Using CQL Filters in the document states report macro Workflow CQL Fields document states report macro
Label	blank	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 reports pages containing any of the listed labels.
Number of items to display	20	The maximum number of results to show per page max is 200
Parent page	blank	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.
Sort	Title	Sort defines the value to sort by with the following options Title Updated Created Created by	v7.2.1+ DATA CENTER
Sort Order	ascending	Sort Order defines the order of the sorting as either ascending descending	v7.2.1+ DATA CENTER
Spaces(s)	@self	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.
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)		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

The document states macro has two parameters to define the sorting of the report (from v7.2.1 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)	6.13+
approvals	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	Date and time the approved (final state) was approved	Date and time v7.2.1+ Duration 6.16+
changed	Date and time of the last state change	Date and time v7.2.1+ Duration 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. A comment added on a state transition is included in the column entry (from v7.6.1 Data Center).	6.13+ Include state transition comment 7.6.1+
created	Date and time of the page creation	Date and time v7.2.1+ Duration 6.16+
created by	The user that created the page	6.16+
due date	Date and time of the state expiry	Date and time v7.2.1+ Duration 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+
state	The current state of the content with the state icon	6.13+
space	The name of the space that the page is in	6.16+
updated	Date and time of the last page edit	Date and time v7.2.1+ Duration 6.13+
updated by	The user that last edited the page	6.13+
workflow	The workflow applied Although page workflows are 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+

Exporting the page

The document states report macro is rendered when a page including the macro is exported to PDF, Word, HTML, or using the macro in a send-email action macro in a workflow trigger.

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)	7.2.3+
approvals	Not displayed
approval status	Not displayed
approved version	Version number in format - v1.1.0 link to the public version of the page (the last version created on the transition to the workflow final state)	7.2.3+
approved version approvers	Comment separated list of usernames that approved the page	7.2.3+
approved version date	Duration since the approved (final state) was approved	7.2.3+
changed	Date in the preferred format of the user	7.2.3+
changed by	Username the user who actioned the last change state change Includes any comment added by the user on the state transition (from v7.6.1 Data Center)	7.2.3+ State transition comment 7.6.1+
created	Date in the preferred format of the user	7.2.3+
created by	Username user who created the page	7.2.3+
due date	Date in the preferred format of the user	7.2.3+
readack status	Status of read confirmation: Pending Completed	7.2.3+
state	The current state of the content	7.2.3+
space	Space name with link.	7.2.3+
updated	Date in the preferred format of the user	7.2.3+
updated by	Username the user who last updated the page	7.2.3+
workflow	Applied workflow name	7.2.3+

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

Send-email trigger export example

The following is an example of a workflow trigger to export the document states report on the change of the applied workflow state to In Progress.

{trigger:statechanged|state=In Progress}
        {send-email:user=admin|subject=Doc States Report}
        {document-states-report}
        {send-email}
    {trigger}