metadata-report macro

Overview

The metadata-report macro shows metadata from matching pages in a tabular report.

You can use the macro to display multiple pieces of metadata from a single page or a group of pages.

Any metadata created with the Comala Metadata App metadata or metadata-list macros can be displayed in the report.

The macro will also retrieve values for any Confluence internal metadata, such as Page alongside metadata created with the Comala Metadata App.

The macro can be used to select:

a selection of multiple metadata values from a single page
a selection of multiple metadata values from a group of pages in the same space or other named space

The macro can also be configured to calculate a sum of all the retrieved values for an individual metadata value name.

Parameters

Parameter	Required	Default	Notes	Version

Parameter	Default	Notes
`Fields`		The list of fields (columns) to be included in the report. This can include added metadata and internal metadata.
`label`		Limits the content to only that which has the specified label(s). A comma separated list produces ANY pages that match, while using + will give ALL pages. Parentheses may be used to build up complex expressions, e.g `\|labels=(yellow,red)+fruit\|`
`key`		Specifies the space key from which the pages are listed.
`root`	`current page (@self)`	Use `@self` for the current page (the default), `@parent` for the parent page, or the name of any page, e.g `MySpace:MyPage`. If this is specified and the pages option is not, then the report will run over only the pages listed here.
pages		Specifies a set of pages to grab from the root page(s). Supports `@children` `@ancestors` `@descendants` `@identity` For example, `\|root=@self\|pages=@children` will give all children of the current page. This can be used in combination with the labels option to find all children with a particular label.
`link`		Specifies which columns in the report should link back to the content.
`maxResults`		Specifies the maximum number of results in a report. Default is 500.
`order`	`descending`	What order should results be sorted in? `ascending` – `A→Z` `descending` – `Z→A` You can combine this with `sort`.
`sort`	`modified`	Specifies which column in the report should be sorted by. You can also include a hint for the sort method before the sort direction. For instance "Name as istring asc" or "Name as istring" will apply a case-insensitive comparison, considering values as string. Other choices include "as date" "as number" "as string" (case-sensitive) Default is case-insensitive comparison.
`totals`		Specifies a comma separated list of values to be totalled.
`type`		Specifies the content type to search within for the specified metadata value names. `page` `blogpost`
`value-name`		The metadata value that will be used for a calculation

Usage

To retrieve multiple metadata values from a page or pages, choose the Metadata report macro from the Confluence macro browser:

The macro editor allows you to configure the macro before you Insert the macro to the page:

metadata report macro browser editor showing fields, space key and link options

The macro requires you to enter at least one metadata value name into Fields. Multiple metadata values can be retrieved by adding a comma separated list of metadata value names.

Adding the metadata value names and choosing to Insert the macro adds the macro placeholder to the page being edited.

This displays a table on the page of the metadata value names and their values from the child pages of the current page.

For example, the macro placeholder above would display the values for three pieces of metadata for each of the child pages:

The retrieved metadata values for the metadata are displayed in a separate row for each child page.

If the metadata value names are not found, or there is no value has added, the table will display the metadata value names specified in the macro but with no value(s) added. The columns are in order of listing of the metadata value names in the macro editor.

Additional options in the macro editor allow you to customise the macro.

Customizing the metadata-report macro to select pages for the report

The choice of source pages for the metadata report can be customized as follows:

Space key determines the space or spaces for the page metadata to be listed
Content type - pages or blog posts
Root defaults to the current page and will report the metadata values on the child pages of the current page

You can choose the root to be parent page of the current page using @parent or the specify the name of a page for the root page. If these are added then the source for the metadata report will be limited to the metadata on the specified root page.

To retrieve the metadata from a related group of pages to a specified root page, you must use the Pages option.

The Pages option can be used with the Labels option to select pages with a particular label from a group of related pages.

Macro Totals option

The report can provide totals for certain columns of metadata values using the Totals option.

In this example two metadata value names are added to the Totals option as a comma separated list:

This displays the metadata values from each page and a sum of their values for each metadata value name:

A null returned metadata value in a column to be summed may result in an error and text based values will return a zero sum.

Other macro options

The macro also has options to:

sort the retrieved metadata values in ascending or descending order.
display a set number of results.

Reference Markup

The basic format of the macro is:

{metadata-report:Name,Author(s),Versions}

This results in a tabular report for the specified on the current page (with three child pages):

Usage with the Comala Document Management app

The metadata-report macro is supported by the Comala Document Management app.