About Metadata for Confluence Server
With the Metadata for Confluence, you can build a lot of different use cases, including IT Documentation. You can define metadata fields that can be combined with metadata sets. You can add them to document templates to make sure that the metadata sets will be filled with information when creating a page from a predefined template.
Below, we describe step-by-step how to set it up in Confluence.
IT Documentation with Metadata for Confluence
Our example describes a simple IT landscape consisting of several servers on which applications run. For each server and each application, we create a wiki page — these have properties and relationships that are maintained via metadata.
As a prerequisite: find or create a Confluence Space for your IT documentation.
1. Create Metadata Fields
In space administration: Let’s create metadata fields for each property. The metadata can have different field types: Text gives you the opportunity to let the user fill in the metadata field with a simple text string. Dropdown gives the user the option to select values from several elements coming from a dropdown menu. User is a metadata field usually connected to a user directory where you can select for example a responsible person. Link fields are one of the most important types because, with it, you can draw connections, for example, to existing pages. Furthermore, you can add restrictions with filters.
The table below shows you which fields you need and how you could configure them:
| Field name | Field type | Field description | Example values |
|---|---|---|---|
| Name | Text | Name of the object | – |
| IP | Text | IP-Adress | – |
| OS | Dropdown | Operating system running | Windows Server 2008, Windows Server 2008 R2, Windows Server 2012 |
| Location | Dropdown | Location of the System (Datacenter/Room) | Datacenter 1, Datacenter 2, Datacenter 3 |
| Vendor | Dropdown | Vendor of the software | Microsoft Corp., Atlassian |
| Contact person | User | Contact person for this object | – |
| Server | Link | Link to Server where the App runs | – |
2. Create Metadata Sets
To use our metadata fields, they have to be included in metadata sets. For this case, we create sets for Server and Application. Now we can add the required fields easily.
The table below shows you which sets you need and which fields have to be assigned there:
| Metadata Sets | ||
| Metadata Field Name | Server | Application |
|---|---|---|
| Name | x | x |
| IP | x | |
| OS | x | |
| Location | x | |
| Contact person | x | x |
| Server (that hosts the application) | x | |
| Vendor | x |
3. Create Templates for a Server and an Application
Now we need to create templates to make use of our metadata sets. With the use of the “Display Metadata” macro, we can display all properties of Server or Application.
The screenshot below shows you how the template for Server could look like:
Interesting here is the macro “Metadata Overview” — it lists applications that are hosted on that server.
The CQL Query “<spacekey>.<Key of Metadata Field “Server>=”PAGEID:$content.id” lists all wiki pages where the Metadata Field “Server (that hosts the application)” is the same as the current page for a server. A deeper understanding of this expert filter criteria provides our documentation.
The screenshot below shows you what the template for Application could look like:
4. Assign the Templates to the Metadata Sets
Click on “Edit” on the metadata set and select the right template for Server and Application metadata sets.
5. Create Main Pages “Servers” and “Applications”
Now we can create main pages for Servers and Applications and add two macros — “Create from template” and “Metadata Overview”.
With the Metadata Overview macro, you can list all applications (or servers) by filtering the results via “Add a filter”. Choose “Metadata Set”: Application.
You might want to add additional options like:
“Create from template” allows us to create a button, which will create a new application page from our template Application.
Create Pages for your Servers and Applications
Congratulations! We have finished the preparation and now, when creating pages for Application and Server from the main pages, the user is able to fill in the metadata attached to the template. While creating a page Application, the user is now able to connect to the Server, where the application is hosted.