This site has moved to the integrated Appfire documentation and information site for our apps.

From February 2024 this site is no longer updated.

Take a look here! If you have any questions please email support@appfire.com

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

Required

Default

Notes

Version

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)



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:

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:

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.

Related Comala Metadata App macros

Related documentation