Content
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). Please refer to the Administrator Guide 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 them by clicking the colorful metadata icon on the top left of the page. Otherwise, your Space Administrator needs to add metadata to the page first.
Image 1: Metadata Icon (click to enlarge) Überarbeitung notwendig!
Clicking the icon leads you to the metadata overview dialog:
Image 2: Metadata Overview Dialog (click to enlarge) Überarbeitung notwendig!
Metadata sets are displayed as headlines with the connected metadata fields below.
Image 3: Edit Metadata (click to enlarge) Überarbeitung notwendig!
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
Editing Metadata takes place in the "Edit Mode". Expand the Metadata Sidebar on the left side of the page to gain access to the Metadata Edit panel.
Image 4: Metadata Icon - Edit Mode (click to enlarge) Überarbeitung notwendig!
The message "Please fill in all required metadata fields." may be displayed when you try to save the page. 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) Überarbeitung notwendig!
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) Ü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
| 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 | Choose the metadata field to filter which fields you want to display from a multiselect dropdown. | ||||||||||||
| Metadata sets filter | None | Optional | Choose the metadata set to filter for a set you want to display from a dropdown.
| ||||||||||||
| 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:
| ||||||||||||
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
| Parameter | Default | Description | |
|---|---|---|---|
| Filters | None | (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 criteria | None | Required | 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:
|
| Metadata fields filter | None | Optional | 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.
|
| 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 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
| Parameter | Default | Description |
|---|---|---|
| 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
global.metadatafield.contactPerson:ksmith
# spaces in the search query global.metadatafield.contactperson : ksmith
# correct search query
global.metadatafield.contactperson:ksmith
Search
Except for the filtering via Expert filter criteria Metadata uses CQL (Confluence Query Language in all of its features. The filtering via Expert filter criteria follows the Confluence Search Syntax which is based on the Lucene search syntax. Lucene search syntax strings may also be used in the Confluence search.
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
Metadata in Confluence Search
As mentioned in the previous section, you may use Lucene search syntax to search for metadata in the confluence search.
If you just search for terms, you can also filter for metadata using the "add filter"-function on search result pages.
Image 12: Metadata in Search Ergänzung notwendig!
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.