User's Guide (v 1.1)
Access and Edit Metadata
Page metadata consists of metadata sets and fields. The metadata sets group several metadata fields together, usually according to a specific topic.The same metadata field can be used in several metadata sets. It will always contain the same value in all of these sets. This means, if you edit the field in one set, the changes will be applied to the field in any one of these sets. Metadata sets may be global (available in all Confluence spaces) or user-created (available in one Confluence space only). However, only Space Administrators are allowed to create either kind of metadata and add it to a page. Please refer to the /wiki/spaces/METADATA/pages/8127038 for further instructions. For users, the distinction is relevant only insofar as the metadata keys are slightly different (see section "Determining the Key of a Metadata Set/Metadata Field").
In View Mode
If a page possesses metadata, you can access and edit them by clicking the colorful metadata icon 
on the top right of the page. Otherwise, your Space Administrator needs to add metadata to the page first.
Image 1: Metadata Icon (click to enlarge)
Clicking the icon leads you to the metadata overview dialog:
Image 2: Metadata Overview Dialog (click to enlarge)
Metadata sets are displayed on the left. The metadata set whose fields are currently displayed is highlighted in blue. In the next column, you can find the metadata field names and next to them, the field values. To edit a metadata field value, click on the pen symbol.
Image 3: Edit Metadata (click to enlarge)
If there aren't any metadata fields to be filled in, your Space Administrator has not added any metadata sets to the page yet.
In Edit Mode
Metadata can be accessed in edit mode as well. When editing a page, click the metadata icon at the bottom left to open the metadata overview dialog.
Image 4: Metadata Icon - Edit Mode (click to enlarge)
The message "Please fill in all required metadata fields." may be displayed when you try to close the overview dialog in either edit or view mode by saving. This message indicates that the available metadata sets contain at least one field marked as "required" that has not been filled in yet. To save your changes, fill in all fields marked with a red "*" (asterisk) and click on "Save".
Image 5: Required Metadata (click to enlarge)
If you do not know the necessary information, you can exit the overview dialog by clicking "Cancel". In that case, none of your metadata changes will be saved.
If you are in edit mode, you will not be able to save changes to a page as long as a required metadata field is empty. Therefore, Space Administrators are encouraged to use required fields sparingly, and only in cases where it is really sensible.
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 the current page.
Image 6: Display Metadata Macro (click to enlarge)
You can display all metadata or only specific sets or fields according to your specifications. Please refer to the following section for the available settings.
Parameters
| Parameter | Default | Description | |
|---|---|---|---|
| Render mode | Table | Optional | Display metadata as name: value pairs (table) or only the value. Several metadata field values will be printed one after the other. Options:
|
| Metadata fields filter | None | Optional | Type your metadata field keys to filter from the metadata sets of the selected page. Use commas to separate multiple sets. E.g.: metadatafield.language |
| Metadata sets filter | None | Optional | Type your metadata set keys you want to display. Use commas to separate multiple keys. E.g. metadataset.document |
| Show hidden metadata fields | None | Optional | Tick the checkbox to show all metadata fields that have been defined as hidden. |
| Checkboxes (Author, Last Modifier,...) | None | Optional | If you tick a checkbox, the respective metadata value will appear as a row in the overview. Available boxes:
|
To determine the keys of your metadata fields and sets, please refer to the section "Determining the Key of a Metadata Set/Metadata Field" below.
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)
The search criterion is defined using the Lycene search syntax (for more details, see section "Search").
Basic search queries can be defined using the following syntax:
//search for user-created set metadataset:KEY_OF_METADATASET //search for user-created field metadatafield:KEY_OF_METADATAFIELD //search for metadata value for a user-created metadatafield KEY_OF_METADATAFIELD:VALUE_OF_METADATAFIELD //search for global set global.metadataset:KEY_OF_METADATASET //search for global field global.metadatafield:KEY_OF_METADATAFIELD //search for metadata value for a global metadatafield KEY_OF_METADATAFIELD:VALUE_OF_METADATAFIELD
Please refer to the section "Determining the Key of a Metadata Set/Metadata Field" to determine the correct keys.
In the next section, you will find an overview of the available settings for the Metadata Overview macro.
Parameters
| Parameter | Default | Description | |
|---|---|---|---|
| Filter criteria | None | Required | The search term specifies the Confluence pages for which metadata shall be displayed. It is defined using the Lycene search syntax (see section "Search"). |
| Metadata fields filter | None | Optional | Define metadata fields to be disaplyed in the overview by their key. If the filter is empty all metadata (except hidden fields) will be displayed. |
| Checkboxes (Author, Last Modifier,...) | None | Optional | If you tick a checkbox, the respective metadata value will appear as a row in the overview. Available boxes:
|
| Sort by column | Page title ("title") | Optional | Defines the metadata field whose values will determine the sort order of all entries. |
| Sort direction | ASCENDING | Optional | Defines the sort direction of the table entries according to the values entered in the "Sort by column" column. |
| Number of items to display | 20 | Optional | Defines the maximum amount of pages that are to be displayed as rows in the macro |
Pages will be found across all (permitted) spaces. This means that search results are not limited to the current space.
Use Cases
(1) Show the metadata of all pages whose metadata sets contain the field "Category":
// Search criteria metadatafield:metadatafield.category
(2) 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 determine 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 8: Metadata History Macro (click to enlarge)
Parameters
| Parameter | Default | Description |
|---|---|---|
| Number of items to display | 10 | Number of displayed 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 overview dialog.
To display the key, go to a page where the metadata field or set has been added. Open the metadata overview dialog by clicking the colorful metadata icon on the top right of the page. Now hover your mouse over the metadata set (in the column on the left) or the metadata field (in the next column) 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 (the current set is hightlighted in blue).
Image 9: Metadata Set Key (click to enlarge)
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 /wiki/spaces/METADATA/pages/8127038.
Image 10: Metadata Field Keys (click to enlarge)
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
global.metadatafield.contactPerson:ksmith
global.metadatafield.contactperson : ksmith
global.metadatafield.contactperson:ksmith
Search
Currently the search used in the Metadata macros follows the Confluence Search Syntax and Confluence Search fields, which are based on the Lucene search syntax. In future releases CQL (Confluence Query Language) will be integrated.
Examples for more complex search
(1) Show the metadata of all pages where the location (a user-created metadata field) is either "Stuttgart" or "Dresden":
// Filter Criteria metadatafield.location:Stuttgart OR metadatafield.location:Dresden
(2) Show the metadata of all pages where the contact person (a global metadata field) is Katherine Smith and the location (a user-created metadata field) is "Dresden":
// Filter Criteria global.metadatafield.contactperson:ksmith AND metadatafield.location:Dresden
(3) Show all pages with the metadata set "projects" in the space "Products" (with key "PROD")
// Filter Criteria metadataset:metadataset.projects AND spacekey:PROD