User's Guide (v 1.2)
- Almuth Boehme [Communardo]
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 added to several metadata sets. It will always contain one and the same value in all of these sets. This means, if you edit the field value in one set, the field value will change in any one of these sets.
Metadata sets may be global (available in all Confluence spaces) or space metadata sets (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 or at the top (depending on your version). 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: Example 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 a specified Confluence page.
Image 6: Display Metadata Macro (click to enlarge)
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
| Parameter | Default | Description | |||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Page | None | Optional | Enter a page whose metadata you want to display. By default, the parameter is empty, which means the current page is selected. Options:
| ||||||||||||
| 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 | Enter the metadata field keys to filter which fields you want to display from the metadata sets of the selected page. Use commas to separate multiple keys. E.g.: metadatafield.language | ||||||||||||
| Metadata sets filter | None | Optional | Type the metadata set keys of the sets 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 (e.g. a common metadata field value).
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 space set metadataset:KEY_OF_METADATASET //search for space field metadatafield:KEY_OF_METADATAFIELD //search for metadata value for a space metadata field 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 metadata field 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.
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
| 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). E.g. metadatafield.status:active (Macro shows the metadata of all pages where the value of the "status" field is "active")
Placeholders are supported to make the output of the macro more dynamic. The following parameters are available:
|
| Metadata fields filter | None | Optional | Define metadata fields to be displayed in the overview by their key. If the filter is empty all metadata (except hidden fields) will be displayed. |
| Show space key | Unchecked | Optional | Display the space key for each page. |
| Show hidden metadata fields | Unchecked | Optional | Display hidden metadata fields as well. |
| 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 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.
Use Cases
(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
| 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/in the top row) 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 highlighted in blue).
Image 10: 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 11: 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
# capital letters used
global.metadatafield.contactPerson:ksmith
# spaces in the search query global.metadatafield.contactperson : ksmith
# correct search query
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 space 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 space 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 space key "PROD")
// Filter Criteria metadataset:metadataset.projects AND spacekey:PROD
Notifications
When metadata values of a page are changed, all watchers of that page get an email notification about the changes made. The email contains the following information:
- Who changed the metadata
- The date and time of the change operation
- Which metadata fields were changed
- Initial and new metadata values of the metadata fields
These email notifications are generated every 15 minutes to avoid sending too many notifications.