Document States Report Macro

Overview

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

This workflow information in the reporting columns 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 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 only see results for content that has reached the Approved ( final=true ) state, even if there are subsequent draft state edits to that content

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

Adding the report

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

In the page editor

choose Insert → 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/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 State filter option for the current report
the Data Refresh option to open the space Data Refresh dashboard 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.

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

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

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
Label	blank	Should the report be filtered by content label(s)? leave empty to include all content add one label name to filter 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 content has all the labels. Otherwise 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 report using the current page as the parent page^☨	^☨@self from v2.0.5 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 current space list multiple space keys, 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.

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.

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

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

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 individual 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	1.8.0+
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 state icon	1.8.0+
updated	Date and time of the last page edit	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, HTML.

The following columns (when included in the report macro configuration) are supported when exporting the page.

Report Column Entry	Export render	Version

Report Column Entry	Export render	Version
title	Page title with full link (including host Confluence instance name)	2.0.6 +
approvals	Not displayed
approval status	Not displayed
approved version	Version number in format - v1.1.0 link to public version of the page (the last version created on transition to the workflow final state)	2.0.6 +
approved version approvers	Comment separated list of usernames that approved the page	2.0.6 +
approved version date	Duration since the approved (final state) was approved	2.0.6 +
changed	Date in preferred format of the user	2.0.6 +
changed by	Username user who actioned the last change state change	2.0.6 +
created	Date in preferred format of the user	2.0.6 +
created by	Username user who created the page	2.0.6 +
readack status	Status of read confirmation: Pending Completed	2.0.6 +
state	Current state of the content	2.0.6 +
space	Space name with link	2.0.6 +
updated	Date in preferred format of the user	2.0.6 +
updated by	Username user who last updated the page	2.0.6 +
workflow	Applied approval workflow name	2.0.6 +

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