Document Stats Report Macro

Owned by Robert Alexander Marshall
Last updated: Jun 17, 2024
6 min read
1 Overview | 2 Permissions | 3 Adding the report | 4 Customizing the report | 5 Report filters | 6 Reporting columns | 7 Why are old states shown? | 8 Related pages

Overview

The Document Stats Report macro displays a count of the content currently in each workflow state.

by default, the workflow information in the report columns includes all the workflow states in the current space (except for the space homepage).

One or more filters can be added to the document-stats-report macro, for example, filter the display to specific states or states in one or more workflows.

Once added to a page, the report macro dynamically updates the count for each state.

Permissions

Anyone can see this report.

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 or blog post.

Pages and blog posts that have not yet been published, or have 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 globally for the instance or in each space.

Adding the report

To add the report to a page choose the Document Stats Report macro.

In the draft page editor, either

  • open the macro editor

    • choose the Confluence header option → Other Macros → Reporting → Document Stats Report

    • choose Insert

  • type {document stats ...  on the page and select Document Stats Report

cdmdc_documentstatsreport_openmacrobrowser.png

Configure the macro settings:

  • choose  Edit the report macro

In the macro editor

  • choose report filters and display column settings

    • scroll down the macro editor to add/edit report additional filter options

By default, the report displays a count for all workflow states including those where no content is currently in the state (count is zero).

  • choose Save to update the macro on the draft page

  • choose Update to add the report to the published page

 

Here's how the report looks on your page.

Customizing the report

Edit the Document Stats report macro to customize the report by

You can choose to filter the state count for the content by

  • label(s)

  • parent

  • space(s) using the spacekey

If multiple labels are added the report displays the state information for content with each label.

To display information for content that must have all the specified labels, add the & (and ampersand) operator in front of the first label in the list

The macro can also be customized for

  • one or more states

  • one or workflows

Filter the report

In the macro editor select options to filter the report. Options include filter by state, space key, label, parent page, and workflow (see table below).

For example, add a filter on the State(s) filter using Published

The filtered report displays only the content with the named state, Published.

If a workflow has been removed from a page in the scope of the report macro, but the document activity has been retained, the report shows the last state information for the content.

Report filters

The filters are listed alphabetically in the macro editor.

Setting

Default

Notes

Label

none

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

  • leave empty to include all content

  • list 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 the content has all the labels. Otherwise, it will report pages containing any of the listed labels.

Parent page

blank (current space home page)

The report is limited to child pages only of the space home page or specified page.

  • leave empty to include all content in the space (does not include the home page as this is the default parent)

  • use @self to  report on the child pages of the current page

  • specify a page title to include only its child pages

In space

blank (current space)

The comma-separated list of space keys to filter.

If multiple spaces are specified, the table counts all content states.

States(s)

blank (all states)

A comma-separated list of states to be displayed in the report. The report displays the count for all the content in each state in the scope of the macro editor settings.

  • leave empty to include all content in all states

  • limit report by listing one or more state names in a comma-separated list

  • states displayed in the report are listed in the order added to the macro (only from v6.16.4+)

The report includes the state count for content where the workflow has been removed but the workflow history has been retained

Workflow(s)

blank (all workflow states)

A comma-separated list of workflows to be displayed.

  • leave empty to include all content in all states in all workflows

  • limit the report by listing one or more workflow titles in a comma-separated list

If left empty then the report includes the state count for content where the workflow has been removed but the workflow document activity has been retained

Reporting columns

The report column order is defined by the entry of the state name column in the macro editor.

The document-stats-report macro can be added to the Confluence chart macro to display the report information.

The Confluence Chart macro display is based on the document-stats-report macro filters

Why are old states shown?

If the table shows states from old Comala workflows that are no longer used, purging the space trash should solve the problem (as any deleted pages in the space trash retain their workflow information).

Report macros

Filter by label

There are no items with the selected labels at this time.