Document Approvals Report Macro

Owned by
Robert Alexander Marshall
Last updated: Jun 26, 2024
9 min read
1 Overview | 2 Permissions | 3 Adding the report | 4 Editing the macro | 5 Customizing the report | 5.1 Reporting columns | 6 Report filters | 7 Exporting the page | 8 Related pages

Overview

v2.1.0+ Data center

The Document Approvals Report displays a list of pages and blog posts with associated workflow approval information for the current state of approval workflows applied to pages.

cdadc_documentapprovalsreport.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 (either the Review or Rejected state for the approval workflow)

  • 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

    • in Comala Document Approval the approval name in both the Rejected and Review state is Review this page

  • 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

    • the page version of the latest approved version (if this currently exists) linking to the latest approved page version

The report displays Pending approvals only. The document approvals report does not show entries for a page with a completed approval as the applied workflow approval has moved to a new state.

The report macro can be customized in the macro editor by choosing

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.

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

Admins can make all results available to everyone by changing the Workflow Activity and Drafts Visibility settings. This is set 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

This is done by either

  • selecting Insert  → Other Macros → Reporting → Document Approvals Report

cdadc_macroeditor_documentapprovalsreport.png

  • 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 repopulates data properties for pages and blog posts with an applied workflow in the current space. This data is used by the Comala Document Approval in-app reporting tools and the report macros.

Editing the macro

On the draft page

  • select the macro

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

Configure the report filters and column display settings In the macro editor.

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 left-hand scrollable panel.

  • the report filter options are

    • Approval name

    • Approval status (only if approval name is specified)

    • 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 the parent page for the report

      • use @self to set the current page as a 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 report displays current approval information. In the Comala Document Approval workflow, approvals that are rejected or approved (all assignees undertake the approval and agree on the approval decision) move to a new state. These completed approvals are not displayed in the report hence only Pending approvals are displayed in 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 - the default setting 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 displayed in each column of the report

  • adding one or more filters

Reporting columns

All columns are displayed in the default report.

Three columns are always displayed in the order below, from left to right, in the rendered report.

  • Page Name; State; Last page update

The display and order of other columns in the report can be customized in the macro editor.

Report column macro editor

Report Column Name

Notes

Report column macro editor

Report Column Name

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

  • state name

  • state indicator circle

last page update

Last page update

  • Avatar of the user who last updated the page

  • date of last page update

approval

Approval Name

Approval name

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

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

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.

  • add the approval name to use the Approval Status filter

 

Approval status

blank

This only applies if an Approval name filter is specified.

Filter by approval status from dropdown menu options

  • Any

  • Pending

Only approvals with a Pending status are displayed.

The following filter options are not for use with the applied Comala Document Approval workflow. Using these filter options does not display any data.

  • Approved

  • Rejected

These two filters are used when a custom Comala Document Management workflow is applied that includes more than one approval in a workflow state.

 

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 

 

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

If using a list of labels, you can prefix the list with  & (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 approval information for the parent page.

 

Spaces(s)

@self

The comma-separated list of space keys to filter.

  • default is @self for current space

  • list multiple space keys, separated by commas, to report on multiple spaces

  • use @all to search all spaces

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

  • 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

The workflow states that including an approval in the Comala Document Approval workflow are

  • Review

  • Rejected

 

Workflow(s)

blank

Displays the Comala Document Approval workflow.

 

Exporting the page

V2.2.0+

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

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

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

2.2.0+

Pending Approvers

User(s) who have not yet undertaken an approval decision for the approval

  • username

2.2.0+

Last page update

Date of last page update

  • user name who undertook last update (user avatar is not displayed

  • date, year in user-preferred format

2.2.0+

Status

  • Current status of approval

    • Pending

    • Approved*

    • Rejected*

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

 

When rendering the exported table for the macro the document approval report macro filter settings are used when displaying the rendered report.

An example of the document approvals report macro rendered on a page exported to HTML is shown below.