User Profiles for Confluence

What the integration provides

• Reuse profile elements as metadata fields: Create Metadata fields of type “User Profile Element” that point to existing single- or multi-select User Profiles elements (for example, Location, Department).

• Single-/multi-select parity: If the selected profile element is single-select, the corresponding Metadata field is single-select as well; if multi-select, the Metadata field supports multiple values.

• Automatic option management: Add new options only once in the User Profiles element; they become available everywhere the mapped Metadata field is used.

• User-aware filtering: Use macro parameters or CQL to match content against the current user’s profile values (for personalized content views).

Prerequisites

• User Profiles for Confluence installed and configured (with relevant profile elements created).

• Metadata for Confluence installed and enabled.

Create a Metadata field from a User Profile element

1. In Metadata administration, add a new field and select the type User Profile Element.

2. Choose a single- or multi-select User Profiles element from the suggestions.

3. Save the field and add it to one or more Metadata sets.

4. When editing a page that uses the set, assign values; the available options mirror the linked profile element.

Safeguards and constraints

• Deletion protection: You cannot delete a User Profiles element if it is referenced by a Metadata field. Remove the Metadata field first to proceed with deletion.

• Add-on availability: If Metadata is disabled or uninstalled, changes to linked User Profiles elements (like deleting options) are not tracked. Re-enabling Metadata later may reveal inconsistencies in stored values.

User-aware content filtering

Two approaches enable filtering by the current user’s profile value for a linked Metadata field.

Macro parameter: User Profile Field Mapping

When at least one Metadata field of type User Profile Element is assigned to a set in your instance, the following macros show an extra parameter that auto-matches against the current user’s profile:

• metadata-overview

• content-by-metadata

Select the desired field in the macro configuration to personalize results for the viewing user.

CQL-based expert filtering

You can use fields of type User Profile Element directly in CQL conditions, including the macros’ expert filter criteria. For example:

MYEXAMPLESPACE.metadatafield.metadataprofilefield = "upc.currentUser"

Where MYEXAMPLESPACE is the key of a space that defines the Metadata field mapped to a User Profiles element, and upc.currentUser instructs the query to match pages whose field value equals the current user’s value for the linked profile element.

Example use cases

• Location-aware announcements: Show regional news to users whose profile Location matches the page’s Location metadata.

• Department-specific documentation: Filter content so engineering, sales, or support see tailored views aligned to their Department profile value.

• Product portfolio pages: Use multi-select Product metadata that mirrors a profile element to target content at users involved in specific products.

Configuration checklist

• Create or verify the necessary User Profiles elements (single- or multi-select).

• Add a Metadata field of type User Profile Element and select the matching profile element.

• Add the field to a Metadata set and apply the set to relevant spaces/content types.

• Use macro parameter User Profile Field Mapping or expert CQL to enable personalized views.

Best practices

• Model once, reuse widely: Centralize controlled vocabularies as profile elements to avoid duplication in Metadata.

• Name consistently: Align the naming of profile elements and Metadata fields for clarity across macros and CQL.

• Change management: Communicate any edits to profile element options to space admins to maintain metadata consistency.

Troubleshooting

• No suggestions when creating a field of type User Profile Element: Ensure at least one compatible User Profiles element exists (single- or multi-select).

• Cannot delete a profile element: Remove dependent Metadata fields first.

• Inconsistent values after re-enabling Metadata: Review changed/deleted options on the underlying profile elements and reconcile affected pages.

Source

User Profiles and Metadata Integration