Macro "Metadata Overview" (v 3.0)

Owned by Almuth Boehme [Communardo]
Last updated: Jun 15, 2020 by Katrin Dreßler
5 min read

In order to insert macros in Confluence, you need to possess editor permissions for the page.

There are several macros you can use to display metadata in Confluence or to select pages on the basis of their metadata. This page will show you how to use the Metadata Overview macro.

Topics include:

Introduction

The Metadata Overview macro is used to display the page metadata of multiple pages in a table according to a search criterion.

An example result can be seen in this preview:


Image 1: Metadata Overview Macro (click to enlarge)


SINCE VERSION 2.0 SINCE CONFLUENCE 5.9

The search criterion is defined by filtering for metadata fields and certain values of those fields or metadata sets. Details on using the CQL dropdown filters are described in Searching with Metadata (v 3.0) and the next section.

Image 2: Adding Filters to Metadata Overview Macro (click to enlarge)

 


  If you want to search for more detailed information, open the expert filter criteria by clicking "Show". This will allow you to, among other things, filter for metadata sets, filter for Confluence spaces or create more complex search queries using Lucene search. Find detailed instructions on how to generate these queries in Searching with Metadata (v 3.0) and some additional information in the next section.
The Metadata Overview will then only show search results that match the expert filter criteria AND selected filters.

You can find more detailed information on the available parameters in the next section.

 

 

Parameters

The following parameters are available for the Metadata Overview macro. To display all of the parameters in the Metadata Overview macro, click "Show" next to the heading "Options".

ParameterDefaultDescription
FiltersNoneOptionalDefine metadata fields and metadata field values, and metadata sets to filter results displayed in the metadata overview macro. Can be left empty if expert filter criteria is used (see next parameter).
Expert filter criteria (CQL)NoneOptional

Define more comprehensive filter queries to filter results displayed in the metadata overview macro. Can be left empty if Filters are used (see prior parameter).

Expert filter criteria are defined using the metadata sets and field keys and the CQL search syntax. Please also see  Determining the Key of a Metadata Set/Field.

Placeholders are supported to make the output of the macro more dynamic.

The following parameters are available:

  • The current page object by using the placeholder $content
    • It is basically the data object used internally by Confluence please see the API Documentation for full capabilities

    • Example: to show all content with metadata links to the current page

      metadatafield.linkfield = "PAGEID:$content.id"
       Other dynamic variables available

      $user.name
      		Current logged in users username
      $user.key
      		Current logged in users userkey
      $user.email
      		Current logged in users email adress
      $user.fullName
      		Current logged in users full name
      $content.contentId
      		The id of the current page/blogpost
      $content.id
      		The id of the current page/blogpost
      $content.type
      		The type of the current page/blogpost
      $content.displayTitle
      		The title of the current page/blogpost
      $content.space.name
      		The name of the current space
      $content.space.key
      		The spacekey of the current space
      $content.space.lowerKey
      		The spacekey of the current space
      $content.space.type
      		The type of the current space

Expert filter criteria (Lucene)

DEPRECATED

NoneOptional

Define more comprehensive filter queries to filter results displayed in the metadata overview macro. Can be left empty if Filters are used (see prior parameter).

Expert filter criteria are defined using the metadata sets and field keys and the Lycene search syntax. Please also see  Determining the Key of a Metadata Set/Field.

Placeholders are supported to make the output of the macro more dynamic.

The following parameters are available:

  • The current page object by using the placeholder $content
    • It is basically the data object used internally by Confluence please see the API Documentation for full capabilities

    • Example: to show all content with metadata links to the current page

      metadatafield.linkfield:$content.id
       Other dynamic variables available

      $user.name
      		Current logged in users username
      $user.key
      		Current logged in users userkey
      $user.email
      		Current logged in users email adress
      $user.fullName
      		Current logged in users full name
      $content.contentId
      		The id of the current page/blogpost
      $content.id
      		The id of the current page/blogpost
      $content.type
      		The type of the current page/blogpost
      $content.displayTitle
      		The title of the current page/blogpost
      $content.space.name
      		The name of the current space
      $content.space.key
      		The spacekey of the current space
      $content.space.lowerKey
      		The spacekey of the current space
      $content.space.type
      		The type of the current space



  • The current user object by using the placeholder $user

    • Example: Show all pages with the current logged in user defnined in a metadata field

      metadatafield.userfield:$user.name
       Other dynamic variables available

      $user.name
      		Current logged in users username
      $user.key
      		Current logged in users userkey
      $user.email
      		Current logged in users email adress
      $user.fullName
      		Current logged in users full name
      $content.contentId
      		The id of the current page/blogpost
      $content.id
      		The id of the current page/blogpost
      $content.type
      		The type of the current page/blogpost
      $content.displayTitle
      		The title of the current page/blogpost
      $content.space.name
      		The name of the current space
      $content.space.key
      		The spacekey of the current space
      $content.space.lowerKey
      		The spacekey of the current space
      $content.space.type
      		The type of the current space

  • The value of a certain field of the user's profile by using the placeholder upc.currentUser.<FIELDNAME>. This parameter works for all field types except multiselect and the About me field. The add-on User Profiles for Confluence needs to be installed.
Metadata fields filterNoneOptional

Define metadata fields to be displayed in the overview from a multiselect dropdown. If the filter is empty all metadata (except hidden fields) will be displayed.

(info) Use this paramter to change the order of the columns. Only the title column will always be displayed as first column.

Show space keyUncheckedOptionalDisplay the space key for each page.
Show hidden metadata fieldsUncheckedOptionalDisplay hidden metadata fields as well.
Common metadata to display (Author, Last Modifier,...)NoneOptional

If you tick a checkbox, the respective metadata value will appear as a row in the overview.

Available boxes:

  • Author - author of the page
  • Last Modifier - person who made the last modification
  • Created at - date of creation
  • Modified at - date of last modification
  • Excerpt - show the excerpt of a page if one is defined with the help of the Excerpt Macro

(warning) If you run into performance issues when displaying excerpts, please use the "number of items to display" option to reduce the amount of displayed pages

Sort by columnPage title ("title")OptionalDefines the metadata field whose values will determine the sort order of all entries.
Sort directionASCENDINGOptionalDefines the sort direction of the table entries according to the values entered in the "Sort by column" column.
Number of items to display20Optional

Defines the maximum amount of pages that are to be displayed as rows in the macro per page. If the overview contains more items, the output will be paged.

(info) The maximum supported number is 250 items. However the performance depends on the number of items as well as the number of columns. You can improve performance by reducing either number.

Title column headingNone ("Title")OptionalChange the heading of the "Title" column.

Show filter

SINCE VERSION 3.0

UncheckedOptional

Show a filter header at the top of the Metadate Overview macro so users can filter the shown results by adding temporary filters.

When adding several filters, only results matching all filter criteria will be shown.

All field types are available for filtering. Changing the filter values will result in realtime search result refresh.

Use the "Filter fields" parameter to predefine permanent filters.

Filter fields

SINCE VERSION 3.0

NoneOptional

Depends on: "Show filter" parameter needs to be checked.

Choose predefined metadata fields for the filter. They will be displayed to all users.

Permissions

Pages will be found across all (permitted) spaces. This means that search results are not limited to the current space unless you filter for a space within the parameter "Expert filter criteria".

The search results are filtered according to the permissions of the logged-in user. This means that you will only see pages you are allowed to access in the Metadata Overview macro.


If the page or space is not otherwise restricted, pages that can be accessed anonymously will appear in the overview macro for anonymous users.

CSV Export

Metadata can be exported as a CSV file. To export metadata, go to a Confluence page whose metadata you want to export and add the Metadata Overview macro to the page. The export option can be found as the following symbol under the Metadata Overview macro:

Image 3: CSV Export Symbol (click to enlarge)


The exported CSV file includes the content of all metadata fields that are displayed in the Metadata Overview macro. By using the macro option "Metadata fields filter" you can define which metadata fields should be displayed and, consequently, exported. The page title of each page is included in the export by default.

Paging of the Metadata Overview does not change the number of results. If you click the export symbol on the first of several pages, you will still export the complete table.

In the next section you will find some examples for the expert filter criteria in the Metadata Overview macro.

Use Cases for Expert Filter Criteria

1) Example from the Metadata demonstration space "Product Directory" - show all pages with the metadata set "Product Info" (metadata set key "democaseproductinfo"), which are part of the space "Product Directory" (space key "DEMOCASEPRODDIR"):

metadataset:metadataset.democaseproductinfo AND spacekey:DEMOCASEPRODDIR

2) Personalization of Confluence content with the help of User Profiles for Confluence - show an overview of all pages with the metadata set "Product Info" where the metadata field "Technology" equals the content of the user profile field "Technology" of the current user:

metadataset:metadataset.productinfo AND metadatafield.technology:upc.currentUser.Technology

For further explanations of this use case, please see How to Get Started. Available options for placeholders are described in the section Parameters above.

You can find further details on basic and complex search queries as well as determining the correct field or set keys in Searching with Metadata (v 3.0).


Back to Top

All Versions