---
title: "metadata-report macro"
canonical: "https://support.appfire.com/space/COMALACM/656579099/metadata-report%20macro"
format: markdown
---
> Macro (aura-html)

## <span style="color: #091e42">Overview</span>

<span style="color: #091e42">The </span>`metadata-report`<span style="color: #091e42"> macro shows metadata from matching pages in a tabular report.</span>

<span style="color: #091e42">You can use the macro to display multiple pieces of metadata from a single page or a group of pages.</span>

<span style="color: #091e42">Any metadata created with the Comala Metadata App </span><span style="color: #091e42">[metadata](https://appfire.atlassian.net/wiki/spaces/COMALACM/pages/655988203)</span><span style="color: #091e42"> or </span><span style="color: #091e42">[metadata-list](https://appfire.atlassian.net/wiki/spaces/COMALACM/pages/655758458)</span><span style="color: #091e42"> macros can be displayed in the report. </span>

![image](media://492f2c15-789a-493e-9428-00643cb1921e)

<span style="color: #091e42">The macro will also retrieve values for any Confluence </span><span style="color: #091e42">[internal metadata](https://appfire.atlassian.net/wiki/spaces/COMALACM/pages/656578765)</span><span style="color: #091e42">, such as </span><span style="color: #091e42">**Page,**</span><span style="color: #091e42"> alongside metadata created with the Comala Metadata App.</span>

<span style="color: #091e42">The macro can be used to select: </span>

- <span style="color: #091e42">a selection of multiple metadata values from a single page</span>
- <span style="color: #091e42">a selection of multiple metadata values from a group of pages in the same space or other named space</span>

<span style="color: #091e42">The macro can also be configured to calculate a sum of all the retrieved values for an individual metadata value name.</span>

## Parameters

| Parameter | Required | Default | Notes | Version |
| --- | --- | --- | --- | --- |
| `Fields` | :check_mark: |  | <span style="color: #000000">The list of fields (columns) to be included in the report. This can include added metadata and internal metadata.</span> |  |
| `label` |  |  | <span style="color: #000000">Limits the content to only that which has the specified label(s).</span><br><span style="color: #000000">A comma-separated list produces ANY pages that match, while using </span><span style="color: #000000">**+**</span><span style="color: #000000"> retrieves ALL pages.</span><br>> ✅ <span style="color: #000000">Parentheses can be used to build up complex expressions, e.g </span>`|labels=(yellow,red)+fruit|` |  |
| `key` |  |  | Specifies the space key from which the pages are listed. |  |
| `root` |  | `current page (@self)` | <span style="color: #000000">Use</span><span style="color: #707070"> </span>`@self`<span style="color: #707070"> </span><span style="color: #000000">for the current page (the default),</span><span style="color: #707070"> </span>`@parent`<span style="color: #707070"> </span><span style="color: #000000">for the parent page, or the name of any page, e.g </span>`MySpace:MyPage`<span style="color: #707070">.</span><br><span style="color: #000000">If this is specified and the pages option is not, then the report runs over only the pages listed here.</span> |  |
| pages |  |  | <span style="color: #000000">Specifies a set of pages to grab from the root page(s). </span><br><span style="color: #000000">Supports</span><span style="color: #707070"> </span><br>- `@children`
- `@ancestors`
- `@descendants`
- `@identity`<br><span style="color: #000000">For example, </span>`|root=@self|pages=@children`<span style="color: #707070"> </span><span style="color: #000000">retrieves all children of the current page. This can be used in combination with the labels option to find all children with a particular label.</span> |  |
| `link` |  |  | <span style="color: #091e42">Specifies which columns in the report should link back to the content.</span> |  |
| `maxResults` |  |  | <span style="color: #091e42">Specifies the maximum number of results in a report.</span><br>> ℹ️ <span style="color: #091e42">Default is 500.</span> |  |
| `order` |  | `descending` | What order should results be sorted in?<br>- `ascending` – `A→Z`
- `descending` – `Z→A`<br>> ✅ You can combine this with `sort`. |  |
| `sort` |  | `modified` | <span style="color: #000000">Specifies which column in the report should be sorted by.</span><br><span style="color: #000000">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.</span><br><span style="color: #000000">Other choices include </span><br>- <span style="color: #000000">"as date"</span>
- <span style="color: #000000">"as number"</span>
- <span style="color: #000000">"as string" (case-sensitive)</span><br>> ℹ️ <span style="color: #000000">Default is case-insensitive comparison.</span> |  |
| `totals` |  |  | <span style="color: #091e42">Specifies a comma-separated list of values to be totalled.</span> |  |
| `type` |  |  | Specifies the content type to search within for the specified metadata value names.<br>- `page`
- `blogpost` |  |
| `value-name` |  |  | <span style="color: #091e42">The metadata value that is used for a calculation</span> |  |

## Usage

> Macro (excerpt)
> 
> To retrieve multiple metadata values from a page or pages, choose the **Metadata report **macro from the Confluence macro browser:
> 
> ![image](media://21abe101-8eeb-47a3-b3a2-2722e1415f96)
> 
> <span style="color: #091e42">The macro editor lets you configure the macro before you </span>**Insert**<span style="color: #091e42"> the macro to the page:</span>
> 
> ![metadata report macro browser editor showing fields, space key and link options](media://53251b15-35e3-445c-a0ab-16713056c10d)
> 
> <span style="color: #091e42">The macro requires you to enter at least one metadata value name into </span><span style="color: #091e42">**Fields**</span><span style="color: #091e42">. Multiple metadata values can be retrieved by adding a comma-separated list of metadata value names.</span>
> 
> <span style="color: #091e42">Adding the metadata value names and choosing </span><span style="color: #091e42">**Insert**</span><span style="color: #091e42"> adds the macro placeholder to the page being edited.</span>
> 
> ![image](media://d8137270-3614-4d40-b374-44ceb8494b2b)
> 
> <span style="color: #091e42">This displays a table on the page of the metadata value names and their values from the child pages of the current page. </span>
> 
> <span style="color: #091e42">For example, the macro placeholder above displays the values for three pieces of metadata for each of the child pages:</span>
> 
> ![image](media://25b84cec-433d-4b06-bf47-0904fd5be9cd)
> 
> <span style="color: #091e42">The retrieved metadata values for the metadata are displayed in a separate row for each child page.</span>
> 
> <span style="color: #091e42">If the metadata value names are not found or no value has been added, the table displays 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.</span>
> 
> <span style="color: #091e42">Additional options in the macro editor let you customise the macro.</span>
> 
> ### <span style="color: #091e42">Customizing the </span><span style="color: #091e42">**metadata-report **</span><span style="color: #091e42">macro to select pages for the report</span>
> 
> <span style="color: #091e42">The choice of source pages for the metadata report can be customized as follows:</span>
> 
> - <span style="color: #091e42">**Space key**</span><span style="color: #091e42"> - Determines the space or spaces for the page metadata to be listed</span>
> - <span style="color: #091e42">**Content type**</span><span style="color: #091e42"> - Pages or blog posts</span>
> - **Root**<span style="color: #091e42"> - Defaults to the current page and reports the metadata values on the child pages of the current page </span>
> 
> <span style="color: #091e42">You can choose the root to be the parent page of the current page using @parent or specify the name of a page for the root page. If these are added, the source for the metadata report is limited to the metadata on the specified root page. </span>
> 
> <span style="color: #091e42">You must use the </span><span style="color: #091e42">**Pages**</span><span style="color: #091e42"> option to retrieve the metadata from a related group of pages to a specified root page.</span>
> 
> ![image](media://f0e2cc64-93f6-4d29-ab2d-b14578780ae5)
> 
> 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

<span style="color: #091e42">The report can provide totals for certain columns of metadata values using the </span>**Totals**<span style="color: #091e42"> option. </span>

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

![image](media://76af6e28-73fd-4aa8-a25e-76613fd3dd55)

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

![image](media://1e2bce17-75fd-48c7-b8cc-383e3856dc31)

> 📝 A null returned metadata value in a column to be summed can result in an error, and text-based values 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

## <span style="color: #091e42">Reference Markup</span>

<span style="color: #091e42">The basic format of the macro is:</span>

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

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

![image](media://49b89c7b-1b19-4aaf-a54f-9201d085c2ec)

## Usage with the Comala Document Management app

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

## Related macros

> Macro (children)

## Related pages

- [Adding metadata to a page](https://appfire.atlassian.net/wiki/spaces/COMALACM/pages/656676899)
- [Retrieving and displaying page metadata](https://appfire.atlassian.net/wiki/spaces/COMALACM/pages/656677227)
- [Using metadata on a page](https://appfire.atlassian.net/wiki/spaces/COMALACM/pages/655988030)
- [Metadata reporting macros](https://appfire.atlassian.net/wiki/pages/createpage.action?spaceKey=comalacm&title=Metadata%20reporting%20macros&linkCreation=true&fromPageId=656579099)