Administrator's Guide (v 1.2)
- Almuth Boehme [Communardo]
Please refer to this guide for instructions on how to install the Metadata add-on, and to make metadata available for pages in a space or globally. The necessary rights for each step are indicated in brackets behind the heading.
Installation (Confluence Administrator)
Installing the Add-on
The add-on is available at the Atlassian Marketplace. To install the add-on, log into your Confluence as a system administrator and navigate to the "Find New Add-ons" tab of the Universal Plugin Manager (UPM) in the global administration. There you simply search for "Metadata". You can find the UPM via the menu entry "Find new add-ons" or similar. For more details about the UPM please refer to the documentation provided by Atlassian.
If the installation is successful and the plugin is enabled, you will see a new colorful icon (
) on the top right of a page (referred to as "page metadata") as well as the entry "Metadata" in the space administration. If that is not the case, you may have not licensed the add-on yet. Please refer to the next section.
Image 1: Space Administration (click to enlarge)
Licensing
The add-on needs a valid license, otherwise features might not work. Valid licenses are either full licenses, renewal licenses, or 30-day trials and are available at the Atlassian Marketplace. The license model is the same that Atlassian uses for its products – for further information see the Atlassian documentation.
Image 2: Add-on Manager (click to enlarge)
To obtain a license and apply it for the add-on, please carry out the following instructions, (also see the screenshot above):
- Go to the license settings page (JIRA Administration -> "Manage Add-ons" or similar tab -> Extend the add-on "Metadata")
- Use the links to create a new license at the Atlassian Marketplace (use "Free Trial" to get a new trial license or "Buy Now" to purchase a full license), or copy a license you may have received from Communardo.
- Enter the license key in the license screen.
The add-on is activated in the Global Administration. Any further administration takes place in the Space Administration. You have to be a Space Administrator to configure the Metadata add-on.
Create Metadata in a Space and Add it to a Page (Space Administrator)
Page metadata consists of metadata sets and fields. The metadata sets group several metadata fields together, usually according to a specific topic. Metadata sets may be global (available in all Confluence spaces) or space sets (available in one Confluence space only). This section describes how to create metadata in a single space (so-called "space metadata"). Please refer to the section Create Global Metadata for information on how to create global metadata.
In order to create and add metadata to a page, you need to be a Space Administrator. You first have to create at least one metadata field and then add the field(s) to a metadata set. Finally, assign at least one metadata set to a page. Please refer to the following documentation for detailed instructions.
Create a Metadata Field
As a space administrator, go to the space you want to add metadata to and click "Space tools" on the bottom left. Then click the entry "Metadata". You will now see the following overview:
Image 3: Space Administration - Metadata Overview (click to enlarge)
Click "Add Metadata Field" on the right. This will lead you to the configuration screen for metadata fields.
Image 4: Add Metadata Field (click to enlarge)
You can now enter a title, choose a field type and enter a description for the field. The title is mandatory.
Fields can have the following type:
- Multi Select (Checkboxes)
- Single Select (Dropdown)
- Link
- Single Select (Radio Buttons)
- Text
- User
When choosing the field type "link", you can restrict which internal links can be selected by the users with the help of a filter. Filters are defined according to the Lucene search syntax.
Image 5: Restrict Internal Links (click to enlarge)
Add Metadata Fields to a Metadata Set
The tab "Metadata Sets" is right next to the tab "Metadata Fields" (cf. previous screenshot). In the tab, click "Add metadata set" on the right to create a new set. This will lead you to the following form.
Image 6: Adding Metadata Fields to a Set (click to enlarge)
You can enter a title (mandatory), a description and select Confluence templates you want to add this set to (for more information on this option, see section "Via Templates" below).
If you check the option "Default Set", this metadata set will automatically be assigned to every newly created page in the current space.
Finally, you can select which already created metadata fields you want to add to this set. You can add space metadata fields as well as global metadata fields. Choose the respective field from the "Metadata Field" dropdown menu, click "Add Metadata Field" and save your changes when you have added all desired fields.
Once a metadata field has been added to at least one set, you have to remove it from all sets before you can edit/delete it again.
Options: Hide and Required
After you have selected a metadata field to add to the set and clicked "Add Metadata Field", it will be added to the overview at the bottom of the page. In that overview, you can check "Hide" or "Required" for every field that has been added.
Image 7: Options Hide and Required (click to enlarge)
Hide: This field will be added to the set, but it will not be displayed when you click the page metadata icon. Please be aware that as a consequence, users will not be able to edit this field.
Required: If you check required, this field has to be provided with a value. If the value is not pre-filled via bulk change, the page metadata overview will pop up automatically when a user edits a page as long as a required field is still empty. The dialog can then only be exited via "Save" if all required fields have been provided with a value. This means neither changes to metadata nor the page itself can be saved as long as required fields are left empty. You are therefore strongly encouraged to mark fields as "required" only if users will be able to provide the necessary information.
You can add the same metadata field to several sets. Internally it is only created once, which means its value is always the same for all sets.
Add Metadata to one or more Pages
There are two conditions:
- First create a metadata set and add at least one field to it
- You have to be a Space Administrator
Once you have created a metadata set in the Space Administration and filled it with at least one field, it is available for the space.
There are three possibles ways to add metadata to one or more pages: Via bulk change, via templates or visiting the page and adding it there.
Via Bulk Changes
Bulk changes are an easy and fast means to add to or change metadata on several pages at once. To make a bulk change, enter the Metadata Administration in the Space Administration and click the tab "Bulk change".
Using the page tree at the bottom of the page, you can add metadata sets to single pages anywhere in the tree, or whole branches of the tree by clicking the top-level page of the branch.
Image 8: Bulk Change (click to enlarge)
- Select the page(s) you want to make changes to in the page tree at the bottom.
- Choose which metadata sets you want to add to the page(s)/remove from them and/or makes changes to in the dropdown menus.
- If you want to change values, enter the value that should be changed (e.g. the user name "Katherine Smith") and what it should be changed to (e.g. "Kathy Smith").
- Finally click "Execute bulk change" to apply the changes.
After clicking "Execute bulk change", a notification will pop up at the top of the page showing which changes have been made.
When changing field values, empty is a valid value. If you leave the first field blank, changes will be made to all empty fields of the type you selected, not all fields. This also works for the field type single select (drop down), if you leave the initial setting "Select".
You can change global fields as a Space Administrator, if you add them to a space metadata set first.
Via Templates
As we have seen earlier, you can add metadata sets to page templates.
To add an already existing metadata set to a template
- Go into the Space Administration > Metadata > Metadata Sets.
- Click "Edit" for the correct metadata set.
- Choose the template in the dropdown next to "Template".
- Finally click "Add Template" and
- Save your changes.
If you check the box "Default Set" before saving your changes, the metadata set is automatically added to every newly created page.
Every time a new Confluence page is created using this template, the chosen metadata set will be automatically added to the freshly created page.
At the Page
Reminder: You have to be a Space Administrator to perform this action.
Last but not least, you can add metadata directly to a page. Choose this option if you want to add metadata to only one page.
- Go to a page and click the colorful page metadata icon on the top right.
- Open the tab "Metadata Sets" and select the sets you want.
- Save your changes.
When you open the page metadata again, you can see the metadata fields that have been configured for the sets you selected. Click the pen symbol to edit them.
Image 9: Editing Metadata (click to enlarge)
Create Global Metadata (Confluence Administrator)
In order to create global metadata, you need to be a Confluence Administrator. Global metadata will be available in all Confluence spaces and helps maintain consistent metadata systemwide. To create global metadata, you first have to create at least one global metadata field and then add the field(s) to a global metadata set. Finally, you can assign your new set(s) to existing pages via bulk change.
Create a Global Metadata Field
As a Confluence administrator, go into the General Configuration and look for "Metadata Plugin" on the left sidebar. Click the entry "Metadata fields". You will now see the following overview:
Image 10: General Administration - Global Metadata Overview (click to enlarge)
Click "Add Metadata Field" on the right. This will lead you to the configuration screen for global metadata fields.
Image 11: General Administration - Add Global Metadata Field (click to enlarge)
You can now enter a title, choose a field type or enter a description for the field. The title is mandatory.
Fields can have the following type:
- Multi Select (Checkboxes)
- Single Select (Dropdown)
- Link
- Single Select (Radio Buttons)
- Text
- User
When choosing the field type "link", you can restrict which internal links can be selected by the users with the help of a filter. Filters are defined according to the Lucene search syntax.
Image 12: Restrict Internal Links (click to enlarge)
Add Global Metadata Fields to a Global Metadata Set
The entry "Metadata sets" can also be found in the "Metadata Plugin" section on the left sidebar. On the page, click "Add metadata set" on the right to create a new set.
Image 13: General Administration - Add Global Metadata Set (click to enlarge)
Check section "Add Metadata Fields to a Metadata Set" above to see how metadata fields will be added to metadata sets. These steps will also work for global metadata.
Determining Metadata Set and Field Keys
As a Space Administrator, go to a page and open "Space tools" > "Metadata". You can find the correct field key in the tab "Metadata fields", set keys in the tab "Metadata sets" respectively.
Image 14: Metadata Field Keys (click to enlarge)
Alternatively, you can go to a Confluence page and open the metadata overview dialog. When hovering over a metadata set or field, the key is displayed as a tooltip. For more details, please check the /wiki/spaces/METADATA/pages/8126763.