Document States Report Macro

Owned by Robert Alexander Marshall
Last updated: Oct 29, 2024 by Alain Martínez
6 min read
1 Overview | 2 Permissions | 3 Adding the report | 4 Customizing the report | 5 Report filters | 6 Reporting columns | 7 Exporting the page

Overview

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

This workflow information in the reporting columns 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 information, including reviewers and decisions

One or more filters can be added to the report macro, for example, workflow states, content label, parent, space(s).

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.

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

  • content that has not yet been published or content under a workflow that does not define a published state is not shown

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

Adding the report

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

  • In the 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

cdc_draftpage_adddocstatesreport.png

  • choose the left-hand panel

    • select report filters

    • configure display column settings

cdcdc_documentstatesreportmacro_macroeditor.png

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/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

  • 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 to repopulate data used by reporting tools and report macros in the space v2.1

Each report column heading can be used to sort the report display alphabetically/chronologically, depending on the chosen column.

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.

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

 

Setting

Default

Notes

 

CQL Filter

blank

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

For CQL field references 

from v1.12.6+, filters can be added using Confluence CQL format and can include OR and comparison operators

 

Label

blank

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

  • 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

If using a list of labels, you can prefix the list with  &  (ampersand) to require that the content has all the labels. Otherwise, it will report 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☨

☨ @self from v2.04 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, 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

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 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

Report Column Entry

Description

Version

title

Page title (always displayed)

1.10.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.10.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.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.

  • a comment added by the user is included in the entry (from v2.3.1+)

1.10.0+

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

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 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.5 +

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)

2.0.5 +

approved version approvers

Comment separated list of usernames that approved the page

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

  • user who actioned the last change state change

  • a 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

  • user who created the page

2.0.5 +

due date

Date in the preferred format of the user

2.0.5 +

readack status

Status of read confirmation:

  • Pending

  • Completed

2.0.5 +

state

The current state of the content

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

  • user who last updated the page

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