---
title: "Document Approvals Report Macro"
canonical: "https://support.appfire.com/space/CDML/741671547/Document%20Approvals%20Report%20Macro"
format: markdown
---
> Macro (aura-html)
## Overview
[v7.3.0+ Data center]
> Macro (excerpt)
>
> The **Document Approvals Report** displays a list of pages and blog posts with associated workflow approval information.
>
> 
>
> The information in the [reporting columns](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649562443/Document+States+Report+Macro#%5BhardBreak%5DReporting-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 ](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649562443/Document+States+Report+Macro#Report-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](https://appfire.atlassian.net/wiki/spaces/CDML/pages/650217543) 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](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649956239)** **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](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649859819). 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](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649528343) and [reporting macros](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649856031).
>
> ## 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.
>
> 
>
> 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
> - **Ancestor page**
> - default is *blank*
> - use **@self** to set the report to list 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**
>
> 
>
> - **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.
>
> 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.
> ℹ️ This column is always displayed in the report and is displayed as the first column in the report. |
> | **state** | **State** | The workflow state that includes the named approval. Entry displays the
- state name
> - state indicator circle
> ℹ️ This column is always displayed in the report and is the second column 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 and is the third column in the report. |
> | **approval** | **Approval Name** | Approval name
> 📝 This is the approval in the workflow state displayed in the same line of the report. |
> | **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
> 📝 Only the approval status is displayed in the document approvals report macro editor preview. |
>
> ## 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
- **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* | A comma-separated list of CQL filters - the values must be indexed.
For versions [v6.16.7](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649790243)+ the CQL format is `Fieldname1=Value 1, FieldName2=Value2`
> ℹ️ For versions prior to v.6.16.7 filter must be added in the form `FieldName1:Value1, FieldName2:Value2`
For CQL field references
- [Workflow CQL Fields](https://appfire.atlassian.net/wiki/spaces/CDML/pages/650250829)
> 📝 The only workflow CQL searchable fields are those listed in the [Comala Document Management CQL Rest API](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649921636) page and [Atlassian Confluence CQL fields](https://developer.atlassian.com/server/confluence/cql-field-reference/). | |
> | **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 content has all the labels. O*therwise, 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 parent page as 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 descendants 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. | v7.7.0+ [DATA CENTER] |
> | **Spaces(s)** | @self | The comma-separated list of space keys to filter.
- default is **@self** for current space
> - list multiple [space keys](https://confluence.atlassian.com/doc/space-keys-829076188.html), 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 | |
> | **Workflow(s)** | | A 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
>
> [v7.5.0+]
>
> The document approvals 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](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649924039) in a workflow trigger.
>
> > 📝 The document approvals report is also supported when exporting a page using
> > 📝
> > 📝 - [K15t Scroll PDF Exporter for Confluence Cloud](https://marketplace.atlassian.com/apps/7019/scroll-pdf-exporter-for-confluence?hosting=datacenter&tab=overview)
> > 📝 - [Snapshot Publishing](https://appfire.atlassian.net/wiki/spaces/AHP/pages/650215885) feature in [Appfire Comala Publishing](https://marketplace.atlassian.com/apps/143/comala-publishing?hosting=datacenter&tab=overview)
>
> The following columns (when included in the report macro configuration) are supported when exporting the page.
>
> | Report Column Entry | Export render | Version |
> | --- | --- | --- |
> | Page Name | Page title with full link (including host Confluence instance name) | 7.5.0+ |
> | State | Current state
> ℹ️ State indicator circle is not displayed. | 7.5.0+ |
> | Last page update | Date of last page update
- user name who undertook last update (user avatar is not displayed
> - date, using user preferred date format | 7.5.0+ |
> | Approval name | Approval name (no link) | 7.5.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. | 7.5.0+ |
> | Pending Approvers | User(s) who have not yet undertaken an approval decision for the approval
- username
> ℹ️ The user avatar is not displayed. | 7.5.0+ |
> | Status | - Current status of approval
> - Pending
> - Approved*
> - Rejected*
> 📝 *In most cases, this status is displayed as **Pending.** as for an **Approved** status the approval transition has usually taken place. An **Approved** or **Rejected** status is only displayed if the state transition has not occurred. For example, if the approval transition has not been added to the state or the state includes a second approval that has yet to be completed.
- 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) | 7.5.0+ |
>
> When rendering the exported table for the macro the document approval report macro filter settings are used to display the rendered report.
>
> An example of the macro on a page exported to HTML.
>
> 
>
> > 📝 If the column choice exceeds 12, 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 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
>
> **[Report macros](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649856031)**
>
> > Macro (children)