The document states macro can be added to a page and configured to report on workflows added to content.

The macro has a number of existing filter options for parent, space key, label.

You can use Confluence CQL to further filter the report to show workflows on grandchildren of a page.

Using the parent filter in the document states report macro

In our scenario, a Comala Document workflow has been applied to all the pages in a group of pages with the Document states report and CQL query page as the top-level page.

We can add the document-states-report macro to a page and filter on the Parent page filter in the macro editor.

The document states report on the published page would only display the children of the Parent page filter. 

The document-states-report macro has an option to add and use some Confluence CQL filters. We can use one CQL filter to expand our display to show all workflows on the pages within a hierarchy.

Adding a CQL filter

 The CQL field reference we will use is ancestor.

This allows the macro to search for all pages that are descendants of a given ancestor page. This includes direct child pages and their descendants. It is more general than the Parent page option in the macro.

CQL filters are added to the macro editor in the following format Fieldname:value.

In our scenario, we will add ancestor:<pageid> where the  <pageid> will be for the highest page in our hierarchy.

  • ancestor:16322274

The content pageid number is displayed at the end of the content url when viewing the Page information option from the page tools menu.


Note that the macro editor accepts CQL format fieldname:value. It does not accept the standard CQL format of fieldname=value.

Once saved to the page the document-states-report displays the workflow state data on the direct descendants of the page identified from the pageid.

Other CQL field references

Multiple CQL field reference filters can be added together to the CQL filter with each field filter being separated by a comma in the macro editor to create a more complex filter.

The CQL filter option works in combination with the other filter options available in the macro editor.

For example, the following report is filtered to content in development category spaces and with the Label option value as index

The CQL filter also accepts 

The following uses Confluence CQL to filter content that is a blogpost using type:blogpost

Other compatible CQL filters include

  • contributor:<username>
  • creator:<username>
  • label:<labelname>
  • title:<pagetitle>

Currently, date based CQL filters are not compatible with the document-states-report macro

Beware that errors may occur when the added CQL filter and the macro option filter overlap. Some complex expressions for for Confluence CQL field references are not supported, for example, multiple values for a field name.

Further details of Atlassian CQL field references are https://developer.atlassian.com/server/confluence/cql-field-reference/

For details of the document-state-report macro filters see - document-state-report macro page