| Table of Contents | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
| Excerpt | ||
|---|---|---|
| ||
Display on a page the Document Approval workflow state information from content across one or more spaces including options to filter to specific states, spaces, parent page, label, space |
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
| Tip |
|---|
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 Visibilitysetting.
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
Status colour Green title 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.
| Info |
|---|
Options are to filter by state, space key, approval name, workflow or CQL (see table below). |
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 | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
CQL Filter | blank | A comma-separated list of CQL filters - the values must be indexed. For CQL field references
Prior to v1.10.5 CQL filter must be in the form | |||||||||
Label | blank | Should the report be filtered by content label(s)?
If using a list of labels, you can prefix the list with | |||||||||
Number of items to display | 20 | The maximum number of results to show per page. | |||||||||
Parent page | blank |
| ☨ @self from v2.0.5
| ||||||||
Sort | Title | Sort defines the value to sort by with the following options
| v2.0.5
| ||||||||
Sort Order | ascending | Sort Order defines the order of the sorting as either
| v2.0.5
| ||||||||
Spaces(s) | @self | Which space(s) should be included in the report?
| |||||||||
State | blank | Should the report be filtered to a specific state or state(s)?
| |||||||||
Workflow(s) | blank | This is redundant as there is only one workflow in the Comala Document Approval app. |
From
| Status | ||||
|---|---|---|---|---|
|
Reporting columns
| Anchor | ||||
|---|---|---|---|---|
|
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
| Status | ||||
|---|---|---|---|---|
|
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 | |||
|---|---|---|---|---|
title | Page title (always displayed) | 1.8.0+ | ||
approvals | Approval(s) in the current specified state
Click each approval icon to show the assigned user(s) | 1.8.0+ | ||
approval status | Displayed as an approval status lozenge
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 document states report is also supported when exporting a page using
The following columns (when included in the report macro configuration) are supported when exporting the page.
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
When the column choice exceeds 12 columns, the rendered table is displayed with columns transposed as rows to ensure fit on the exported page. The export may also generate additional table(s) in the rendered export when there are 12 entries or more.