Document Approvals Report macro (2)

Overview

v2.1.0+ Data center

The Document Approvals Report displays a list of pages and blog posts with associated workflow approval information.

cdmdc_documentapprovalsreport_default_onpage_threeentries.png

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 who 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. This is great for tracking 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.

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 see the results for content that has reached a Published ( final=true ) state, even if subsequent draft state edits exist. 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 by changing the Workflow Activity and Drafts Visibility settings in the current space configuration or for all the 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
publish the updated page

You can do this by either

selecting Insert → Other Macros → Reporting → Document Approvals Report
type {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.

cdmdc_documentapprovalsreport_default_onpage_twoentries_nodisplayed_filters_norefresh.png

The default report displays information for current workflow approval for pages and blog posts with an applied workflow in the current space.

Move your mouse over the report entries to display the report filters and the Data Refresh options.

cdmdc_documentapproavslreport_onpage_withfilters_refreshdata.png

The Refresh Data option opens the space Refresh Data dashboard. This dashboard repopulates data properties for pages and blog posts with an applied workflow in the current space. The Comala Document Control in-app reporting tools and report macros use this data.

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.

You can configure the report filters and column display settings in the macro editor.

Mouse over the preview to display the on-page filter buttons.

The filter and display options are displayed alphabetically in the 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 the & (ampersand) to require a match for all added labels
- Parent page
  - default is blank
  - sets the space home page as the parent page for the report
  - use @self to set the current page as the parent page for the report
- Ancestor page
  - default is blank
  - report only on ancestor pages of a specified page
  - use @self to report on the ancestor pages of the current page
- 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

documentapprovalareport_macroeditor_extract_columns_info.png

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

The report does not list pages with approvals in the Rejected or Approved status if a transition from the workflow state containing the approval has occurred.

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.

You can customize the columns displayed in the report using the macro editor. However, the columns Page Name, State, and Last page update are always shown in the rendered report and displayed in the order below.

cdmc_documentapprovalreport_minimum_numberofcolumn_display.png

Report column macro editor	Report Column Heading	Notes

Report column macro editor	Report Column Heading	Notes
title	Page Name	Name of the page with the applied workflow that includes an approval. This column is always displayed in the report. It is the first column in the report.
state	State	The workflow state with the named approval. Each column entry displays the state name state indicator circle This column is always displayed in the report.
last page update	Last page update	Avatar of the user who last updated the page date of last page update This column is always displayed in the report.
approval	Approval Name	Approval name Reports on the approval in the listed workflow state in the same report line.
approvers	Approvers	User(s) who have undertaken an approval decision for the named approval user avatar displayed with icon appending depicting the most recent approval decision for that use (tick - approved; cross - rejected)
pending approvers	Pending approvers	User(s) assigned to the approval and have not yet undertaken an approval decision for the named approval user(s) avatar
status	Status	Approval status Pending Rejected Approved If a transition to a workflow final state has occurred, the version number for the last approved version is displayed. this version number links to the last approved version of the page The version number is only displayed on the published page, not in the macro editor preview.

Report filters

The filters are listed alphabetically in the macro editor.

Report filter setting	Default	Notes

Report filter setting	Default	Notes
Approval name	blank	Name of the approval
Approval status	blank	The filter is only applied if an Approval name* filter is specified.* Filter by approval status from dropdown menu options Any Approved Pending Rejected
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 for the current user viewing the report on the page @self displays only approvals assigned to the user viewing the page with the document approvals report macro
CQL Filter	blank	For CQL field references Workflow CQL Fields Comala Document Management document states report macro From v1.12.6, filters can be added using Confluence CQL format and can include OR and comparison operators Before v1.12.6, the CQL filter must be in the form `FieldName:Value`
Label	blank	Should the report be filtered by content label(s)? leave empty to include all content specify one label name to filter to that label list multiple label names, separated by commas, to filter to content with any of those labels Using a list of labels, you can prefix the list with the & (ampersand) to require that the content has all the labels. Otherwise, it reports pages containing any of the listed labels.
Number of items to display	20	The maximum number of results to show per page max is 200
Parent page	blank	leave empty to set the parent page as the home page for the space specify a page title to filter to its child pages The report does not include the parent page. The parent parameter accepts the @self value reference.
Ancestor page	blank	The report is limited to the descendant pages of the specified page. use @self to report on the descendant pages of the current page specify a page title to include only its descendant pages If specifying an ancestor page, you cannot list multiple space keys. The report defaults to the descendant pages of the added page.	v2.4.0+ DATA CENTER
Spaces(s)	@self	The comma-separated list of space keys to filter. 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 Live filtering is not active when more than one space is specified.
State(s)	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)		comma-separated list of one or more workflows to display approval report information You can only filter this column on space workflow names. There is no option to filter on the name of a page workflow.

Exporting the page

V2.2.0+

The document approvals report macro is rendered when a page that includes the macro is exported to PDF, Word, or HTML.

The document approvals 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.

Report Column Entry	Export render	Version

Report Column Entry	Export render	Version
Page Name	Page title with full link (including host Confluence instance name)	2.2.0+
Approval name	Approval name (no link)	2.2.0+
State	Current state The state indicator circle is not displayed.	2.2.0+
Approvers	User(s) who have undertaken an approval decision for the approval username user decision approved/rejected date of the approval/rejection in the user-preferred date format The user avatar and approval decision icon are not displayed.	2.2.0+
Pending Approvers	User(s) who have not yet undertaken an approval decision for the approval username The user avatar is not displayed.	2.2.0+
Last page update	Date of last page update user name who undertook the last update (user avatar is not displayed) date, using the user-preferred date format	2.2.0+
Status	Current status of approval Pending Approved* Rejected* In most cases, this status is displayed as Pending.* An Approved or Rejected status is only displayed if the state transition has not occurred. Confluence version number of the last approved version in the format - v17 links to the public version of the page (the last version created on the transition to the workflow final state)	2.2.0+

The exported table is rendered using the filter settings in the macro.

An example of the document approvals report macro on a page exported to HTML.

document approvals report macro - rendered on page exported to HTML

If the column choice exceeds 12, columns might be transposed as rows to ensure fit on the exported page. When there are 12 entries or more, a page export can generate one or more additional tables in the rendered export.