Document Approvals Report Macro
Overview
v7.3.0+ Data center
The Document Approvals Report displays a list of pages and blog posts with associated workflow approval information.
The information in the reporting columns for the default report is
Page Name - includes a link to the page with the applied workflow with the approval
State - workflow state containing the approval
Last page update - an avatar for the user last updated the page, the date of the last page update
Approval name - the name of the workflow state approval
Approvers - avatars of users who have approved or rejected the named approval appended with an icon for their most recent approval decision
Pending Approvers - avatars of users assigned to the approval as a reviewer and are yet to undertake an approval decision
Status - the approval status and the page version of the latest approved version (if this currently exists) linking to the latest approved page version
One or more filters are available in the report, for example, filter the workflow information based on approval status for a named approval.
Once added to a page, the report macro dynamically updates the displayed information. It's great for keeping track of content workflow approvals across multiple spaces.
If a workflow approval has moved to a new state, the document approvals report does not show the completed approval.
Approvals with a status of Rejected or Approved are only visible if there has not been a transition out of the workflow state where the approval resides.
For instance, if no approval transition has been added for the state, or if multiple approvals are required for the transition to happen.
Permissions
Anyone can see this report. The report only shows information that matches the current user permissions for the page, blog post, and 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. Content that has not yet been published, or under a workflow that does not define a published state, is not displayed.
Admins can make all results available to everyone by changing the Workflow Activity and Drafts Visibility settings. This can be set in the current space configuration, or for all spaces in an instance in the global configuration.
Adding the report
To add the report to a page select and add the Document Approvals Report macro to a draft page. This done by either
selecting Insert
→ Other Macros → Reporting → Document Approvals Report
typing {Document Approvals ... and select Document Approvals Report
Edit the configuration in the macro in the editor or choose Save to use the default macro settings.
Publish or Update the page to view the default report on the page.
The default report displays information for current workflow approval for pages and blog posts with an applied workflow in the current space.
Report filters and the Data Refresh option are displayed by moving the mouse over the report entries.
The Refresh Data option opens the space Refresh Data dashboard. This space dashboard is used to repopulate data properties for pages and blog posts with an applied workflow in the space. This data is used by Comala Document Management in-app reporting tools and reporting macros.
Editing the macro
On the draft page
select the macro and choose Edit
The macro editor displays the document approvals report macro configuration options and a preview of the default document approvals report for workflows applied in the current space.
In the macro editor, you can configure the report filters and column display settings.
Mouse over the preview to display the on-page filter buttons and the option to Refresh Data for the reports.
The filter and display options are alphabetically displayed in the macro editor's left hand scrollable panel.
the report filter options are
Approval name
Approval status (only if approval name is specified)
dropdown option to filter approval status: Any; Pending; Approved; Rejected
Assignee
use @self to display the current user viewing the report reviewer assignments
CQL filter
Label(s)
comma-separated list of one or more labels to filter
prefix list with “&” ampersand to filter requiring a match for all added labels
Parent page
default is ”blank”
sets the space home page as parent page for the report
use @self to set current page as parent page for the report
Space(s)
default is @self for the current space
use @all to search all spaces
add a comma-separated list of space keys to search selected spaces
Workflow(s)
comma-separated list of workflow names to filter for the report
The display options for the filtered report are
columns displayed
by default, the comma-separated list title, state,approvers,pending approvers,last page update,status
Number of items to display, by default, is 20 items per page
On configuring the report macro filters and display options, choose
Save to update the macro on the draft page
Publish or Update the draft page to add the report on the published page
Customizing the report
Edit the Document Approvals report macro to customize the report by
choosing the information to be displayed in each column of the report
adding one or more filters
Reporting columns
All columns are displayed in the default report.
The choice of columns in the displayed report can be customized in the macro editor except for Page Name; State; Last page update. These three columns are always shown in the rendered report and are displayed in the order shown below.
Report column macro editor | Report Column Heading | Notes |
|---|---|---|
title | Page Name | Name of the page with the applied workflow that includes an approval. |
state | State | The workflow state that includes the named approval. Entry displays the
|
last page update | Last page update |
|
approval | Approval Name | Approval name |
approvers | Approvers | User(s) who have undertaken an approval decision for the named approval
|
pending approvers | Pending approvers | User(s) assigned to the approval and have not yet undertaken an approval decision for the named approval
|
status | Status | Approval status
If a transition to a workflow final state has occurred, the version number for the last approved version is displayed.
|
Report filters
The filters are listed alphabetically in the macro editor.
Report filter setting | Default | Notes |
|
|---|---|---|---|
Approval name | blank | Name of the approval |
|
Approval status | blank | This only applies if an Approval name filter is specified. Filter by approval status from dropdown menu options
|
|
Assignee | blank | Name of the user assigned as an approver. Displays only approvals to which the user has been assigned as a reviewer or has already undertaken an approval decisions
@self displays only approvals assigned to the user viewing the page with the document approvals report macro |
|
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 |
|
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. |
|
Spaces(s) | @self | The comma-separated list of space keys to filter.
Specifying more than one space or all spaces disables live filtering. |
|
State(s) | blank | Should the report be filtered to a specific state or state(s)?
|
|
Workflow(s) |
| A comma-separated list of one or more workflows to display approval report information. |
|
Send-email trigger export example
The following is an example of a workflow trigger to export the document approvals report on the change of the applied workflow state to Review.
{trigger:statechanged|state=Review}
{send-email:user=admin|subject=Doc Approvals Report}
{document-approvals-report}
{send-email}
{trigger}Related pages
Other pages