Skip to end of metadata
Go to start of metadata

You are viewing an old version of this content. View the current version.

Compare with Current View Version History

« Previous Version 2 Next »

Content


Macros

There are several Confluence macros you can use to display metadata or select pages on the basis of their metadata in Confluence.

In order to insert any of the macros, you need to possess editor permissions for the page.

Display Metadata Macro

The Display Metadata macro shows metadata of a specified Confluence page.


Image 6: Display Metadata Macro (click to enlarge) Überarbeitung notwendig!

You can display all metadata or only certain sets or fields according to your specifications. Please refer to the following section for the available settings.

Parameters

ParameterDefaultDescription
PageNoneOptional

Enter a page whose metadata you want to display. By default, the parameter is empty, which means the current page is selected.

Options:

ValueOutput
EmptyMetadata of current page
Specific Confluence pageMetadata of specified page
@parentMetadata of the current page's parent page
@rootMetadata of the current page's root page
@homeMetadata of the current page's home page
Render modeTableOptional

Display metadata as "name: value" pairs (table) or only the value. Several metadata field values will be printed one after the other.

Options:

  • Table
  • Value
Metadata fields filterNoneOptional

Choose the metadata field to filter which fields you want to display from a multiselect dropdown.
Only the metadata of the selected page will be available for selection.

Metadata sets filterNoneOptional

Choose the metadata set to filter for a set you want to display from a dropdown.

 

Show hidden metadata fieldsNoneOptionalTick the checkbox to show all metadata fields that have been defined as hidden.
Checkboxes (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

If both filters (metadata fields and metadata sets) are empty, all metadata (except hidden fields) will be displayed.

Use Cases

(1) Display all page metadata in a table.

(2) Keep your site up-to-date using metadata. By choosing the render mode "value" and entering a specific field key, you can display single metadata values wherever you need the information.

Metadata Overview Macro

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 7: Metadata Overview Macro (click to enlarge) Überarbeitung notwendig!

The search criterion is defined by filtering for metadata fields and certain values of those fields.

Image 8: Darstellung Filterabfragen

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 8: 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 an overview of the available settings for the Metadata Overview macro.

Parameters

ParameterDefaultDescription
FiltersNone(Required)Define metadata fields and metadata field values to filter results displayed in the metadata overview macro. Can be left empty if expert filter criteria is used (see next parameter).
Expert filter criteriaNoneRequired

Define more comprehensive filter queries to filter results displayed in the metadata overview macro. It is defined using the metadata sets and field keys and the Lycene search syntax. Please also see Determining the Key of a Metadata Set/Metadata Field and #Search.

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
  • The current user object by using the placeholder $user
  • 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.
Checkboxes (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
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 display20OptionalDefines 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.

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".

Use Cases for expert filter criteria

(1) Show the metadata of all pages whose metadata sets contain the field "Category":

// Search criteria metadatafield:metadatafield.category

(2) To get an overview of her own projects and their status, Katherine Smith might show the metadata of all pages where the contact person (a global metadata field) is Katherine Smith:

// Search criteria, using the login name of a user global.metadatafield.contactperson:ksmith

For the syntax of basic search queries, please refer to the beginning of this section. To determine the correct field or set keys, please refer to the section Determining the Key of a Metadata Set/Metadata Field below. To find out how to design more detailed search queries, please refer to the section Search

Metadata History Macro

The Metadata History macro displays the metadata history of the current page:


Image 9: Metadata History Macro (click to enlarge)

Parameters

ParameterDefaultDescription
Number of items to display

10

Number of displayed entries

If the metadata of the page never changed before (after beeing published), the macro will show no history entries.

Determining the Key of a Metadata Set/Metadata Field

Confluence users can determine the key of metadata fields or sets by moving their mouse over the metadata set or field title within the metadata edit panel.

To display the key, go to a page where the metadata field or set has been added. Open the metadata edit panel in edit mode. Now hover your mouse over the metadata set (in the column colored in blue) or the metadata field (entries below) whose key you want to know. A small tooltip containing the respective key will be shown.

If you cannot find the metadata field, check if you have selected the correct metadata set.


Image 10: Metadata Set Key (click to enlarge) Überarbeitung notwendig!

As a Space Administrator, you can find the correct field key in the tab "Metadata fields", set keys in the "Metadata sets" tab respectively, as described in the Administrator Guide.  


Image 11: Metadata Field Keys (click to enlarge) Überarbeitung notwendig!

Troubletshooting

When entering keys in a macro, make sure:

  • There are no spaces
  • They are written completely in lower case
  • Words are only divided by "." (full stop) or ":" (colon) respectively, if you are searching

 

# capital letters used
(error) global.metadatafield.contactPerson:ksmith

# spaces in the search query
(error) global.metadatafield.contactperson : ksmith

# correct search query
(tick) global.metadatafield.contactperson:ksmith

 

  • No labels