metadata-matches macro

Overview

The metadata-matches macro totals up the number of matching pages which have a particular value for metadata. This result can be shown directly or can be used as input to another statistics macro.

In addition, this macro allows for another metadata value to be calculated for each matching page. If another metadata value name is specified the macro will display a calculation based on the values of this metadata on the matching pages rather than the count of the number of occurrences.

Parameters

Parameter	Required	Default	Notes	Version

Parameter	Default	Notes
first parameter		The metadata value name whose values will be matched. This can include added metadata and internal metadata. The value of the metadata to be matched is added to the macro placeholder (macro body). If a `value-name` is NOT specified for a calculation in the `value-name` field, then the macro will return a count of the number of occurrences of this first parameter metadata value specified in the body of the macro placeholder.
`function`	sum	If a `value-name` is specified for a calculation, then the macro will use the specified `function` on the values taken from the matching pages and display the calculated value of this `function.` `sum` - returns the sum of each non-empty value (default) `average` - returns the average of each non-empty value `maximum` - returns the minimum of each non-empty value `minimum` - returns the maximum of each non-empty value The metadata value that is compared includes any wiki markup characters used for the value.
`key`	`current space`	Limits the content returned to be within the space with the given key.
`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.
`label`		lImits the content to that with the specified label or labels. A comma separated list produces ANY pages that match.
`type`		Specifies which Confluence content types should be considered for a report. This feature is based on the Confluence contentbylabel macro which has the same attribute.
`value-name`	`sum`	Second metadata value that can be used to generate a calculation - the default is `sum`. However it can also apply the same functions as used in the `metadata-calculate` macro.

Usage

To retrieve the number of pages with a particular value for metadata, choose the Metadata matches macro from the Confluence macro browser:

The macro editor requires the metadata value name to be added:

The value for the metadata is added to the macro placeholder

The value added to the macro placeholder must include all the value - here the value includes some wiki format.

In this example, the page where the macro is added will display simply the sum of the number of pages with matching metadata values for the Current Lifecycle status metadata value name:

This value can be used for other Confluence statistical macros such as the Confluence Chart macro.

Adding a metadata value-name for a calculation of the values on the matched pages

Adding a metadata value name to the value-name option in the macro editor adds the ability to perform calculations on the values of a specified metadata on the matching pages.

In our example above, the metadata-matches macro displays the count of the number of child pages where the Current Lifecycle status metadata has a value of |Active|.

If another metadata is added to the value-name field the macro will perform a calculation on the values of this second metadata for any occurrences on the matching pages.

In the example, in the macro editor:

adding an existing metadata name, Feb Hours

choosing the function as sum

amends the macro placeholder to show the added value-name parameter

The macro body still contains the metadata value |Active|, the macro will only perform the calculation on the pages with this matching value.

The page display will show the sum based on the values of Feb Hours on the matching pages:

In the example, across the matching pages where the metadata Current Lifecycle status has a value of |Active|, the sum of the metadata Feb Hours values is 84.

Another example of use of the metadata-matches macro is to add multiple versions of the macro to populate a table, creating a dashboard of information from a group of pages

Multiple versions of the metadata-matches macro can also be added to the Confluence chart macro to visualise and present the collated data from each report.

Reference Markup

{metadata-matches:Current Lifecycle status}|Active|{metadata-matches}

The macro will retrieve the number of times the Current Lifecycle status metadata values for the child pages of the current page are equal to |Active|.

If there is any formatting as part of the metadata value, this must be included in the body of the metadata-matches macro.

The report is displayed as a count of the number of pages that currently with this value for the metadata.

If a calculation is required for a metadata value on these matching pages, an example of the markup required for the default sum of these values is:

{metadata-matches:Current Lifecycle status|value-name=Feb Hours}|Active|{metadata-matches}