Using a CQL filter in the document states report macro to report on grandchildren of a page
Overview
The document states report macro can be added to a page and configured to report on the workflows added to the content.
You can use Confluence CQL to further filter the report to show workflows on the grandchildren of a page.
The macro has a number of existing filter options for parent, space key, label.
Prior to v6.16.5 CQL filter must be in the form FieldName:Value. The standard CQL format of fieldname=value is accepted for v6.16.5+
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.
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 following uses Confluence CQL to filter content that is a blogpost using type=blogpost
Further details of Atlassian CQL field references are https://developer.atlassian.com/server/confluence/cql-field-reference/
Details of the macro filters can be found on the document states report macro page.