| Table of Contents | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Overview
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
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 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 dynamically updates the displayed information. It's great for keeping track of content workflow states across multiple spaces.
| Info |
|---|
From v7.3.0, use the Document Approvals Report Macro to display approvals in the state and approval information including reviewers and decisions |
Permissions
Anyone can see this the report, but the information displayed may be is filtered by the user permissions for the content pages 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 contentpage. Content A page that has not yet been published, or content under a page with an applied workflow that does not define a published state, will 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
| Status | ||||
|---|---|---|---|---|
|
Moving the cursor over the report on the page displays an option to Refresh Data for the report
| Status | ||||
|---|---|---|---|---|
|
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 also displayed in the macro editor by moving the cursor over the report preview.
Editing the macro
On the draft page
choose Edit the macro
choose report filters and display column settings
scroll down In the macro editor to
add/edit report filter optionsconfigure the report
columnsdisplay
options by default. By default
columns displayed are the comma-separated list title, state, changed, updated by, updated
- by default,
the report displays 20 items per page
sort order of report is descending on the 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, approval status, approvals,updated by, updated 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
Displays the page, the current state, and the date of last state change.
| Info |
|---|
Title is always the first column displayed |
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.
The document states report can be configured to include columns that display state approval-related information. From v7.3.0, macro approval-related filters are only available in the Document Approvals Report macro.
Filter the report
In the macro editor select options to filter the report. These include options to filter by state, space key, approval namelabel, workflow or CQL filter (see table below).
For example, add a filter on the Approval name State filter using QA ReviewDraft
The filtered report displays only the page(s) with currently in the named QA Review approvalstate, Draft.
The report macro can also filter approvals on approval status and approval assignee.
| Info |
|---|
If a workflow has been removed from content a page or blog post that is in the scope of the report macro, but the workflow document activity history has been retained, the report will show shows the last state information for the contentpage or blog post. |
Report filters
The filters are listed alphabetically in the macro editor.
Setting | Default | Notes | Approval assigned to | blank | The user assigned to an approval. Options
| Approval name | blank | Name of the approval | Approval status | blank | Only applies if an Approval name filter is specified. Filter by approval status from dropdown menu options
| |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
CQL Filter | blank | A comma-separated list of CQL filters - the values must be indexed. For versions v6.16.7+ the CQL format is
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. | ||||||||||
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 |
The report does not include the parent page.
| ||||||||||
Sort | Title | Sort defines the value to sort by with the following options
| v7.2.1
| |||||||||
Sort Order | ascending | Sort Order defines the order of the sorting as either
| v7.2.1
| |||||||||
Spaces(s) | @self | The comma-separated list of space keys to filter.
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)?
| ||||||||||
Workflow(s) | A comma-separated list of workflows to be displayed. You can only filter this column on space workflow names. There is no option to filter on page workflow names. |
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
| 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 | Version |
|---|---|---|
title | Page title (always displayed) | 6.13 + |
approvals | Approval(s) in the current specified state
Click each approval icon to show the assigned user(s) From v7.3.0 use the Document Approvals Report Macro to display and filter approval information | 6.13 + |
approval status | Displayed as an approval status lozenge
If no approval is present in the current state, no approval status is displayed From v7.3.0 use the Document Approvals Report Macro to display and filter approval information | 6.13 + |
approved version | The approved (final state) page version version From v7.3.0 use the Document Approvals Report Macro to display and filter approval information | 6.16 + |
approved version approvers | The user(s) that caused the page to enter the final state From v7.3.0 use the Document Approvals Report Macro to display and filter approval information | 6.16 + |
approved version date | Date and time the approved (final state) was approved From v7.3.0 use the Document Approvals Report Macro to display and filter approval information | 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 | 6.13 + |
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:
| 6.16 + |
state | The current state of the content with 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
| 6.16 + |
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.| Info |
|---|
For the CQL alias for each column item see the document states report macro page. |
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 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
If the column choice exceeds 12 columns the rendered table may be displayed with columns transposed as rows to ensure fit on the exported page. Export also may generate additional table(s) in the rendered export when there are 12 entries or more.
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.
| Code Block |
|---|
{trigger:statechanged|state=In Progress}
{send-email:user=admin|subject=Doc States Report}
{document-states-report}
{send-email}
{trigger} |
All examples
| Filter by label (Content by label) | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
|