---
title: "Document Tasks Report Macro"
canonical: "https://support.appfire.com/space/CDML/943194589/Document%20Tasks%20Report%20Macro"
format: markdown
---
> Macro (aura-html)
> Macro (excerpt)
>
> Report page macro displays information for tasks and associated information for each page v7.5.0+
## Overview
[V7.5.0+]
> Macro (excerpt)
>
> The **Document Tasks Report Macro** displays details about workflow tasks and related information for each page in one or more spaces.
>
> 
>
> On the page, a live filter is available to display information by the user assigned to a task.
>
> The report macro can be configured in the macro editor to [filter](https://appfire.atlassian.net/wiki/spaces/AWPD/pages/edit-v2/941686990#Filtering-the-report) the displayed workflow task information.
>
> Once added to a page, the report macro dynamically updates the displayed information.
>
> ## Permissions
>
> Anyone can see the report, but the information displayed is filtered by the user permissions for the pages and the workflow state.
>
> > 📝 [View-only users](https://appfire.atlassian.net/wiki/spaces/CDML/pages/650217543) see results only for content that has reached a Published (** **`final=true`** **) state, even if there are subsequent draft state edits to that page. A page that has not yet been published or a page with an applied workflow that does not define a published state are not shown.
>
> 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.
>
> ## Adding the report macro
>
> To add the report to a page, choose the **Document Tasks Report** macro using either
>
> - the macro editor on the draft page by choosing **Insert ** ** > Other Macros > Reporting > Document Tasks Report**
>
> 
>
> - or on the draft page type **{Document Tasks ...** and select** Document Tasks Report**
>
> 
>
> Publish the page to view the default report
>
> 
>
> The default report displays information for each page and blog post in the current space **@self**
>
> - with an added workflow task
>
> The default report display is a maximum of 20 report entries.
>
> > 📝 Displayed report entries are per page. If a page has more than one task, the page is one line in the report and this report line displays all the tasks for the page.
>
> Sort the report by **Page** title (alphabetically, ascending or descending).
>
> Move the cursor over the report to display
>
> - the **Assigned to** live filter to choose a task assignee to filter the report display on the page
>
> 
>
> - the **Refresh Data** option to open the space [Refresh Data dashboard](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649859819)
>
> 
>
> The space tools refresh data dashboard option is used to refresh the workflow properties data used by in-app reports and report macros.
>
> ## Editing the macro
>
> On the draft page with the Document Tasks Report macro added
>
> - choose **Edit** the macro
>
> By default the macro displays
>
> - all workflow tasks
> - in the current space
> - for all task assignees
> - all unassigned tasks
>
> The report displays the workflow task information displayed
>
> - in columns - **title**,** state**,** task, status, assigned by, assigned, assigned to, due date, actual time spent**
> - 20 items per page
>
> Displayed items are displayed by page, not by task. A single page with multiple tasks is displayed as one line in the report
>
> ## Customizing the report
>
> ### Customize the number of items displayed
>
> Customize the displayed report in the macro editor to set the number of entries displayed in the report on the page.
>
> 
>
> The default setting displays 20 items. Any additional items over this value paginate the report.
>
> > 📝 A page is defined as one item. A page with multiple tasks is considered a single item in the report.
>
> For example, a report for a space with 3 pages with workflow tasks customized to display 2 items shows a page with multiple workflow tasks as one item line.
>
> 
>
> The total number of pages is appended to the bottom right of the report display.
>
> Mouse over the report to display the navigation to additional report pages.
>
> 
>
> ### Filter the report
>
> In the macro editor, select one or more options to filter the report. These include options to filter by pending task assignee, state(s), parent page, space key(s), label(s), workflow(s), or CQL filter (see [Report filters](https://appfire.atlassian.net/wiki/spaces/AWPD/pages/edit-v2/941686990#Report-filters) below).
>
> For example, add a filter on the **Pending task assignee **filter using user **Suni Conn**.
>
> 
>
> The filtered report displays only page(s) with a pending task (tasks status of [ACTIVE]) assigned to the named user.
>
> ## Report filters
>
> One or more filters can be set for the report in the macro editor.
>
> - scroll down in the left panel to add one or more filters
> - use the **Preview** option to preview the report information
>
> 
>
> | | | | |
> | --- | --- | --- | --- |
> | Filters | Default | Notes | Version |
> | **Pending task assignee** | *Blank* | User assigned to a task
- filter displays only pending tasks assigned to the user
> ℹ️ Value is used to populate the report **Assigned to** live filter on the page. | **Document Tasks Report Macro **is available in
- v7.5.0+ |
> | **CQL Filter** | *Blank* | A comma-separated list of CQL filters - the values must be indexed.
> 📝 The CQL format is `Fieldname1=Value 1, 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(s)** | | 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 a page 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
> 📝 One item is defined as a page. A page with multiple tasks is single item in the report | |
> | **Parent page** | *Blank* | - specify a page title to filter the report to its child pages
The report includes the parent page if there is no parent page set.
> ℹ️ 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] |
> | **State(s)** | *Blank* | Comma-separated list of state names to filter
- filters report to the current workflow state of the page | |
> | **Space(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. | |
> | **Workflow(s)** | *Blank* | 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 using a page workflow name. | |
>
> ## Reporting columns
>
> All columns are displayed by default. There is no configuration option for the display of columns in the report.
>
> The displayed columns are
>
> - **Page** - page or blog post name
> - on a page, this column can be used to sort the displayed reported
> - **State **- current workflow state
> - **Task** - task name
> - **Status** - task status
> - **Active** [ACTIVE]
> - **Completed** [COMPLETED]
> - **Assigned by** - the user who assigned the task to a user
> - displays the user avatar and user name
> - **Assigned** - date of task assigned to a user
> - **Assigned to **- user assigned to the task (if assigned)
> - displays the user avatar and user name
> - **Due Date** - due date (if set) for completion of the task
> - **Actual time spent** - time elapsed since the task was assigned
> - displayed in hours
> - no value is displayed if no user is assigned to the task
> - **Completed** tasks display the period from task assignment to completion
>
> > 📝 Completed tasks [COMPLETED] are displayed in the report but related task events are not shown. Refer to the document activity report on each page for details of the task including the user who completed the task.
>
> ## Exporting the page
>
> The document tasks report macro is rendered when a page that includes 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 tasks 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)
>
> When rendering the exported table for the macro the document tasks report macro filter settings are used to display the rendered report.
>
> | Report Column Entry | Export render |
> | --- | --- |
> | Page | Page title (with full link including host Confluence instance name) |
> | State | Current workflow state of the page or blog post
> ℹ️ No state indicator circle is displayed |
> | Task | Task name |
> | Status | Task status
- Active
> - Completed |
> | Assigned by | Username
- user who assigned the task to a user
> ℹ️ No link or avatar is included for the user. |
> | Assigned | Date of task assignment
- date is in user preferred format |
> | Assigned to | Username
- user who is assigned to the task
> ℹ️ No link or avatar is included for the user. |
> | Due Date | Date set for completion of the task
- date is in user-preferred format |
> | Actual Time Spent | Elapsed time since task assignment
- days or hours
> - for example, **2 Day(s)** or **6 Hour(s)**
> - **Completed **tasks display the period from assignment to task completion |
>
> An example of the rendered document tasks report on a page exported to HTML:
>
> 
>
> > 📝 By default, exporting to PDF or Word a page with an applied workflow with a final state exports the last approved version of the page.
>
> ### Send-email trigger export example
>
> The following is an example of a workflow trigger to include in a workflow that exports the document tasks report on the change of the applied workflow state to **Triage Tasks**.
>
> ```
> {trigger:statechanged|state=Triage Tasks}
> {send-email:user=admin|subject=Document Tasks Report}
> {document-tasks-report}
> {send-email}
> {trigger}
> ```
>
> ## Related pages
>
> - [Tasks Report - Space Tools](https://appfire.atlassian.net/wiki/spaces/CDML/pages/650152506)
> - [Document Actions Report - Profile](https://appfire.atlassian.net/wiki/spaces/CDML/pages/650152557)
> - [Document Actions Report Macro](https://appfire.atlassian.net/wiki/spaces/CDML/pages/943292642)