Document Tasks Report Macro

Overview

V7.5.0+

The Document Tasks Report Macro displays details about workflow tasks and related information for each page in one or more spaces.

cdmdc_documentasksreport_onpagewithpagetitle_threepages_fourtasks.png

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 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 only see results 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 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

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 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 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	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. For CQL field references Workflow CQL Fields
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. 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	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.
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, 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.

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

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 in a workflow trigger.

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
Task	Task name
Status	Task status Active Completed
Assigned by	Username user who assigned the task to a user
Assigned	Date of task assignment date is in user preferred format
Assigned to	Username user who is assigned to the task
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:

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}