Overview

The {document-states-report} macro is used to create custom reports on workflow states, reviews and tasks.

Where to use it?

Optional.

One or more {document-states-report} macros can be used in wiki pages, blog posts, and, in some cases, comments - see Reporting Guide > Reporting Macros > Document States Report Macro

It can also be used in any macro which supports wiki content in its Macro body (check relevant macro documentation for details).


Parameters

Parameter

Required

Default

Notes

Ver

approvalName


all

The name of a content review.

  • Leave empty to include all content

The name is defined by the {approval} macro and is shown in the Workflow Popup during Content reviews.


approvalAssignedTo


all

Should the report be filtered to content that the specified user(s) has been assigned to review? Value is one or more usernames separated by a comma..

  • Leave empty to include all content
  • Specify a username to filter to results which that user is assigned to review
  • Specify @self to filter to results that the current user is assigned to review

approvalStatus
all

Only applies if an approval name filter is specified, which stage of the content review should the content be in?

  • pending – the review is not yet complete
  • approved – the review was approved
  • rejected – the review was rejected

columns

title+, state, changed, updated by, updated

The report columns displayed in the UI on the content can be set to be one or more of:

  • from Comala Document Management 6.13.0 the following columns are available
Column name displayed in the reportColumn parameter in the macro
Titletitle
Statestate
Approvalapprovals
Approval Statusapproval status
Changed Bychanged by
Updated Byupdated by
Updatedupdated

+title item is always displayed in the report.

  • from Comala Document Management 6.16.0 the following additional columns are available
Column name displayed in the reportColumn parameter in the macro
Approved Versionlast final version
Approved ver. approved bylast final version approvers
Approved ver. datelast final version date
Createdcreated
Created bycreated by
Due datedue date
Read Confirmationreadack status
Spacespace
Workflowworkflow

Columns are displayed in the order the items are added in the macro editor.

The following column headings are sortable in the UI of the report (from v6.16.6+)

  • Title
  • Created
  • Due date
  • Read Confirmation
  • State
  • Updated
  • Created by
  • Workflow


v6.13+













v6.16+

content-title
allFilter report for specific named content.

filter


all

You can provide a comma-separated list of CQL filters – the values must be indexed.

(info) The only workflow CQL searchable fields are those listed in Comala Document Management CQL Rest API page together with the Atlassian Confluence CQL fields

Other Atlassian CQL resources


(info) from v.6.16.7+  filters can be added using Confluence CQL format and can include OR and comparison operators

(warning) prior to v6.16.7 CQL filter must be in the form FieldName:Value

v6.16.7+

label



Should the report be filtered by content label(s)?

  • Leave empty to include all content
  • Specify one label name to filter to a specific 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.


maxItems


20

The number of results to show per page.


order


descending

What order should results be sorted in?

  • ascendingA→Z
  • descendingZ→A

parent



Should the report be filtered to a specific parent page and the child pages of the specific page?

  • Leave empty to include all content in the space
  • Specify a page title to include the specified page and its child pages
  • Specify @self to specify the current page

sort


modified

Which report column of the report should results be sorted by?

  • modified – the most recent date on which the content (page or blog post) was modified
  • pagestate – the current workflow state
  • statechanged – the most recent date on which the state was changed
  • title - the content title
  • approval status - pending, approved, rejected
  • approvals - approval name

space


current space

Which space(s) should be included in the report?

  • Leave empty to report on the current space
  • Specify one space key to report on a specific space
  • List multiple space keys, separated by commas, to report on multiple spaces
  • Specify any to report on all spaces

state


all

Should the report be filtered to specific 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
all

Should the report be filtered to states in a specific workflow(s)?

  • Leave empty to report on all states in all workflow
  • Specify one workflow name to report on states in that workflow
  • List multiple workflow names, separated by commas, to report on specific states in those workflows

(info)  You can only specify space workflow names. There is no option to specify a page workflow name.



All examples

See also

Workflow Authoring Guide

Reporting Guide

Developer Guides