Skip to main content
Skip table of contents

Filter news by metadata (like location, category)


Metadata for Confluence allows you to assign and administer page metadata in Confluence centrally.

With the Metadata add-on, you can:

  • Assign metadata sets to single pages, part of or even the whole page tree of a space

  • Add metadata sets to Confluence page templates

  • Search metadata and display pages based on their metadata values  

Why use the Metadata Add-on in combination with the Enterprise Theme?

As explained in the introduction, you can provide metadata for pages and blog posts, for example the target country or department for a blog post and use this metadata to define specific news listings etc.

If you use the Enterprise Theme News macros like the Blog Posts & Pages, you can list content based on exactly this metadata. If you use the User Profiles Add-on in addition, the Enterprise Theme macros can filter their content by dynamic Metadata queries, based on the information of the current logged in user. 

Some examples what can be built with this? 

  • Blog Post listings for a specific country

  • Blog Post or Pages listings about a specific topic

  • News for the department, the current logged in user is working for! (Combination of Enterprise Theme, Metada Add-on and User Profiles App)

  • Show all news for a specific department AND the global news

  • ...

Which Enterprise Theme Macros can use Metadata Information?

Some macros can use the metadata information within their macro configuration. These macros are implementing the Lucene query parameter of the news macros. You can use the parameter in these macros:

How to use Metadata Information in the Enterprise Theme macros

All Enterprise Theme News macros provide an input field for a Lucene Query parameter. With this parameter you are able to enter every lucene query you like. A detailed documentation about this parameter can be found under the Lucene query parameter of the news macros.

The Communardo Metadata Add-on extends the search index with every metadata field value you create in that add-on.

To use the metadata field values with the news macros you need to follow these steps:

  1. Find the name of the Metadata field used in the index

  2. Use the name to build a valid Lucene query

  3. Add this query to the news macro parameter Additional Lucene Query (The Lucene query parameter of the news macros)

Search Terms Based on Lucene Search Syntax 

Search queries according to the Lucene search syntax necessitate knowing the keys of metadata sets and fields. Basic search queries look like this:

//search for space set

//search for space field

//search for metadata value for a space metadata field

//search for global set

//search for global field

//search for metadata value for a global metadata field

//do not allow an empty field
metadatafield.KEY_OF_METADATAFIELD:[* TO *]

However, you do not have to guess the correct name. The following section describes how to determine the keys of metadata sets/fields.

Determining the Key of a Metadata Set/Field 

As a User

Confluence users can determine the key of metadata fields or sets by moving the mouse over the metadata set or field title within the metadata overview.

Image 1: Metadata Set Key (click to enlarge)

To display the key, go to a page where the metadata field or set has been added. Open the metadata overview by clicking the colorful Metadata icon at the top-left. Now hover your mouse over the metadata set (displayed at the top) 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.

As a Space Administrator

For the following steps, you need Space Administrator permissions.

As a Space Administrator, you can additionally go to a page and open "Space tools" > "Metadata". To find the correct metadata field key, click the tab "Metadata fields" or open the tab "Metadata sets". 

Space metadata fields are displayed at the top, global metadata fields at the bottom.

Image 2: Metadata Field Keys (click to enlarge)   



When entering keys of metadata fields or sets in a macro or the Confluence search, make sure that:

  • There are no spaces

  • They are written completely in lowercase

  • Words are only divided by "." (full stop) or ":" (colon) respectively, if you are searching.

# capital letters used
(error) global.metadatafield.contactPerson:ksmith

# spaces in the search query
(error) global.metadatafield.contactperson : ksmith

# correct search query
(tick) global.metadatafield.contactperson:ksmith

Examples for the Syntax of a Lucene Query 

All news macros of the Enterprise Theme provide an input field for a Lucene query parameter. You can enter any valid search query to filter the results.

The only thing you need is the correct syntax, to be able to filter by metadata information.

Basic search terms with Lucene search syntax are explained at the beginning of this section. Find more complex examples below.

1) Show all pages where the location (a space metadata field) is either "Stuttgart" or "Dresden":

// Lucene Query
metadatafield.location:Stuttgart OR metadatafield.location:Dresden

2) Show all pages where the contact person (a global metadata field) is Katherine Smith and the location (a space metadata field) is "Dresden":

// Lucene Query 
global.metadatafield.contactperson:ksmith AND metadatafield.location:Dresden

3) Show all pages with the metadata set "projects"

// Lucene Query 

Advanced Usage

4) Filter by the User Profile

The Enterprise Theme allows you to combine more in our content macros 🙂 If you use the User Profiles Add-on by Communardo you can combine the User Profile information to use the profile information of the current user. This allows you to provide a very user specific content listing in the Enterprise Theme Macro.

// Lucene Query

The part upc.currentUser.Location will be replaced by the location of the user (if such field exists). More information about this feature can be found in Use the Communardo User Profiles app with the Enterprise Theme News Macros and in the macro documentation of the Top Stories Slider, Blog Posts & Pages and News Boxes macros.

Parts of this documentation were copied from the Metadata documentation.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.