Add Menu Categories Using Archetypes

Last modified 13 Jul 2026 15:18 UTC

This how-to guide explains how to add menu categories to the midPoint GUI using archetypes.

Introduction

You can use archetypes to create dedicated menu subcategories in the midPoint GUI main navigation menu. This allows you to provide users with focused entry points to specific groups of objects (for example, managers, contractors, or service accounts) while also using the archetypes to define their policy, display, and lifecycle characteristics.

You can apply menu subcategories to most object types, most commonly UserType, RoleType, OrgType, and ServiceType. For the full list of supported holder types, refer to Archetypes.

In general, you can use the following configuration patterns to define menu categories:

  • Archetype-based — Recommended when objects need a persistent classification that drives policy, display, and lifecycle behavior.

  • Object collection-based — Suitable for ad-hoc views defined by a filter rather than object membership.

This guide covers the archetype-based approach but it also uses object collection views to reference archetypes in the system configuration.

In this how-to, we will create a new Managers menu category under the Users section of the main navigation menu.

Managers menu category added to Users

Prerequisites

  • A running midPoint instance.

  • Administrative privileges sufficient to create archetypes and modify systemConfiguration.

  • Optional: familiarity with the midPoint XML schema for the manual configuration paths.

Configuration overview

Implementing a menu category via archetypes requires the following configuration steps:

  1. Define an archetype that targets a specific holder type and carries the display metadata (label, icon, colour).

  2. Register the archetype in systemConfiguration under adminGuiConfiguration/objectCollectionViews so it surfaces in the navigation menu.

Step 1 — Configure archetype

Configure the holder type

The holder type binds the archetype to a specific object class (for example, UserType). It determines which object types can be assigned the archetype and, consequently, where the category will appear in the GUI.

Holder type assignments cannot currently be configured through the GUI. XML editing is required.

In the archetype that you want to use as your menu category, paste the following XML snippet to configure the holder type. Replace UserType with the desired holder type. In the GUI, you can do this by opening the archetype and clicking Edit raw.

Holder type configuration in XML
<archetype>
    ...
    <assignment>
        <identifier>holderType</identifier>
        <activation>
            <effectiveStatus>enabled</effectiveStatus>
        </activation>
        <assignmentRelation>
            <holderType>UserType</holderType>
        </assignmentRelation>
    </assignment>
    ...
</archetype>

For details on assignment relations, see Archetype Configuration.

Configure display attributes

Display the attributes that control how the archetype is rendered in the menu and in the object detail views, i.e., label, plural label, tooltip, and icon. These can be configured either through the GUI or directly in XML.

GUI

  1. Open the target archetype and click Archetype policy.

  2. Expand the Archetype policy > Display section and set the following:

    Attribute Example value

    Label

    Manager

    Plural label

    Managers

    Tooltip

    Manager

  3. Expand the Icon section and set the following:

    Attribute Example value

    CSS class

    fa fa-user

    Color

    green
    Archetype configuration in GUI

  4. Save the archetype.

XML

<archetype>
    ...
    <archetypePolicy>
        <display>
            <label>
                <t:orig>Manager</t:orig>
                <t:norm>manager</t:norm>
                <t:translation>
                    <t:key>Manager.label</t:key>
                </t:translation>
            </label>
            <pluralLabel>
                <t:orig>Managers</t:orig>
                <t:norm>managers</t:norm>
                <t:translation>
                    <t:key>Managers.pluralLabel</t:key>
                </t:translation>
            </pluralLabel>
            <tooltip>Manager</tooltip>
            <icon>
                <cssClass>fa fa-user</cssClass>
                <color>green</color>
            </icon>
        </display>
    </archetypePolicy>
    ...
</archetype>

The cssClass attribute accepts any Font Awesome icon class as well as classes from the Evolveum font-evosome icon set. The color attribute accepts any valid CSS color value, including named colors and RGB hexadecimal notation (for example, #3a8a3a).

Step 2 — Register the archetype in system configuration

Once the archetype is defined, it must be referenced from systemConfiguration so that the GUI renders it as a menu category.

In objectCollectionViews, add a new objectCollectionView element that references the archetype created in the previous step. The type element must match the holder type defined in the archetype (in this example, it is UserType), while the collectionRef element must reference the archetype’s OID.

Example XML configuration for objectCollectionViews
<systemConfiguration>
    ...
    <adminGuiConfiguration>
        <objectCollectionViews>
            ...
            <!-- Reference to the archetype created in Step 1 -->
            <objectCollectionView>
                <type>UserType</type>
                <collection>
                    <collectionRef
                        oid="73732a88-3a9e-456e-9db8-1212107b39c2"
                        relation="org:default"
                        type="c:ArchetypeType"/>
                </collection>
            </objectCollectionView>
            ...
        </objectCollectionViews>
    </adminGuiConfiguration>
    ...
</systemConfiguration>

Verification

After applying the configuration:

  • The new category appears under the corresponding object type in the main navigation menu, rendered with the configured label, and icon.

  • The category is offered as a selectable archetype on the New user (or equivalent) creation screen.

Managers menu category added to Users

Menu changes may be cached in your user session. If the new category does not appear immediately, log out and log back in to force the GUI configuration to reload.
Was this page helpful?
YES NO
Thanks for your feedback