Advanced dashboard configuration options

Last modified 17 Sep 2025 13:27 +02:00
Dashboard feature
This page describes configuration of Dashboard midPoint feature. Please see the feature page for more details.
Table of Contents

This article contains advanced configuration options for dashboards and dashboard widgets in particular. You can use the options to select the data sources for your widgets or adjust the appearance of your dashboard widgets, including conditioning the appearance so that you get a visual warning when there are, for example, users with too many high-privilege roles.

The widget element can contain three configuration elements: display,data, and presentation which you can use to configure what the widget looks like, whence it takes the data, and how it presents the data to users.

We recommend using IntelliJ IDEA with the midPoint Studio plugin. Engineering midPoint with Studio is definitely much easier.

Define data sources for widgets

The data element defines the source of the data that the widget displays.

To take off lightly, here is the simplest possible example of a widget with an object collection as its data source:

<widget>
    ...
    <data>
        <sourceType>objectCollection</sourceType>
        <collection>
            <collectionRef oid="15de186e-1d8c-11e9-a469-8f5d9cfc0259" type="c:ObjectCollectionType"/>
        </collection>
    </data>
</widget>

The table below contains more details about the configuration options you have regarding the data sources.

Table 1. Configuration options for the data element
Name Type Description

sourceType

DashboardWidgetSourceType

Specify the type of input data for generating a message shown in the widget. Possible options are:

  • objectCollection: Content of the widget is based on an object collection.

  • auditSearch: Content of the widget is based on the data from an object collection with a filter for audit records. See also Collection report: Audit Report, Attribute Changes.

  • object: Content of the widget is based on the data from a single object.

displaySourceType

DashboardWidgetSourceType

Use this element in asynchronous widgets to select the data source the widget uses for displaying data.

For asynchronous widgets, set this to widgetData. Although the widget data source (sourceType) may be, e.g., an object collection, a report can save the computed data into the widget object and the widget can then display the saved data without querying midPoint objects through the collection de novo.

The widget in the GUI usually contains a More info button which takes users to a details page with objects queried using the sourceType element configuration.

Refer to the simple example of sourceType and displaySourceType elements usage beneath the table. See also Dashboards configuration introduction for a full tutorial on the topic.

collection

CollectionRefSpecificationType

Specify which object collection should the widget use to query midPoint objects. The element contains a collectionRef element with a reference to the particular collection.

objectRef

ObjectReferenceType

Specifies a single object as a data source for the widget.

storedData

String

Specifies a string as a widget data source. The string can be stored by a report task. Use this configuration for asynchronous widgets.
An example of a simple asynchronous widget
<widget>
    ...
    <data>
        <sourceType>objectCollection</sourceType> (1)
        <displaySourceType>widgetData</displaySourceType> (2)
        <collection>
            <collectionRef oid="15de186e-1d8c-11e9-a469-8f5d9cfc0259" type="c:ObjectCollectionType"/> (3)
        </collection>
        <storedData>25/25 runnable</storedData> (4)
    </data>
</widget>
1 The source from which the data for the widget to display are computed.
2 The instruction for the widget to display the data it has saved in itself. These data have been saved to the widget by a report.
3 The object collection used as the primary source of the widget data.
4 The string here displays only before the connected report runs for the first time. The report overwrites this value.

You can use an objectCollection, auditSearch or object as a data source for asynchronous widgets. Regardless the widget data source, for asynchronous widgets, you need to use the displaySourceType element with the widgetData value.

Use specific object as a widget data source

Another option is to define a specific object as a source. In this case, a part of the configuration is a reference to the object which is used as the source. The configuration contains a path to the attribute which is presented in the widget.

An example of a widget querying the execution status of a task object
<widget>
    <c:identifier>report-task-status</c:identifier>
    <data>
        <sourceType>object</sourceType>
        <objectRef oid="ed05a4ae-e39f-465a-bd56-35c41fb97bd1" type="c:TaskType"/>
    </data>
    <presentation>
        <dataField>
            <fieldType>value</fieldType>
            <expression>
                <c:path xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="t:ItemPathType">$object/executionState</c:path>
            </expression>
        </dataField>
    </presentation>
</widget>

The widget may render as follows:

Dashboard widget showing the execution status of task
Figure 1. Dashboard widget showing the execution status of an explicitly selected task.

Define widget visual and presentation attributes

There are two elements for visual configuration of widgets:

  • The display element: Use to adjust the appearance of your widgets, such as the default color and icon.

  • The presentation element: Use to select the data presentation style or condition the appearance based on the data. Furthermore, the view element within the presentation element serves to configure the report that can be created based on the dashboard configuration.

Visual configuration

The display attribute contains configuration of the widget visual side in the GUI.

Table 2. Configuration options for the display attribute
Name Type Description

label

String

Displayed name of widget.

color

String

Default background color of the widget.

icon/cssClass

String

CSS class for widget icon; e.g., fa fa-user.

cssStyle

String

CSS style for the widget; e.g., color: #444 !important.

Presentation of widget data

The presentation element contains options to define how the widget presents the data. It consists of dataField elements using which you adjust the displayed data.

Each dataField element has one fieldType element that states of what type the field is. There are two field types currently supported:

  • value: Use to specify the presentation style of the widget data.

  • unit: Use to specify the unit for the data.

The other element in dataField elements is expression:

  • In the case of value-type field, the expression element holds the proportional element with the presentation style element.

  • In the case of unit-type field, the expression element holds the value element that specifies the string shown after the number (e.g., users, tasks, roles).

Data presentation configuration skeleton - two dataField elements, one for the value, one for the unit
<presentation>
    <dataField>
        <fieldType>value</fieldType>
        <expression>
            <proportional>
                <style><!-- your chosen presentation style --></style>
            </proportional>
        </expression>
    </dataField>
    <dataField> (1)
        <fieldType>unit</fieldType>
        <expression>
            <value><!-- your custom unit string --></value>
        </expression>
    </dataField>
</presentation>
1 The order of the dataField elements is not significant. The presentation style dictates how the data is presented.

There are four presentation style options:

MidPoint Dashboard showing various widget data presentation styles: total number, percentage, X/Y, and X out of Y.
Figure 2. Four dashboard widgets showing various available data presentation styles

The available presentation styles are:

  • A number of objects in the collection and no information about the collection domain

    • For example, 8

    • <style>value-only</style>

  • Percentage of objects in the collection as compared with the collection domain

    • For example, 25%

    • <style>percentage</style>

  • A number of objects in the collection shown with the number of objects in the domain, delimited by the slash (/) character

    • For example, 8/32

    • <style>value-slash-domain</style>

  • A number of objects in the collection shown with the number of objects in the domain, delimited by of

    • For example, 8 of 32

    • <style>value-of-domain</style>

You can see the configuration for the dashboard in the image above in the code below.

Presentation style configurations

View on GitHub

Variation of widget data

The next presentation element is variation. This element allows for conditional variation of the widget appearance. Variations may change the color or icon of the widget based on specific conditions.

Table 3. Configuration options to define a widget display variation based on a condition
Name Type Description

condition

ExpressionType

Condition for the variation. The variation activates when the condition evaluates to true.

display

DisplayType

Display properties to be applied when the condition evaluates to true. These display properties specify only the presentation aspects that differ from the default presentation. For example, if the variation only changes the widget color, only the color needs to be specified here. Icons and other visual attributes are taken from the primary widget display properties.

You can use four variables for condition:

Table 4. Variables on which you can base the variation condition
Name Type Description sourceType in data of widget

proportional

IntegerStatType

Integer stat (statistic) entry. This entry contains stat value, together with domain value.

objectCollection, auditSearch

policySituations

Collection <String>

Collection of policy situations

objectCollection

object

Based on the displayed object in the widget

Processed object

object

storedData

String

Data stored in the widget

widgetData
Example of a variation based on policy situation conditions 
<widget>
    ...
    <presentation>
        <dataField>
            <fieldType>value</fieldType>
            <expression>
                <proportional xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="c:ProportionalExpressionEvaluatorType">
                    <style>percentage</style>
                </proportional>
            </expression>
        </dataField>
        <dataField>
            <fieldType>unit</fieldType>
            <expression>
                <value>up</value>
            </expression>
        </dataField>
        <variation>
            <condition>
                <script xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="c:ScriptExpressionEvaluatorType">
                    <code>
                        policySituations.contains("#resourceHealthDanger")
                    </code>
                </script>
            </condition>
            <display>
                <color>#dd4b39</color>
            </display>
        </variation>
    </presentation>
</widget>

Configure the object collection overview

The last element of the presentation container is view. This element is processed when creating reports. The main reason to configure the view element is to customize the report that is based on the dashboard widget or adjust the object collection screen.

In the graphical user interface, the object collection screen is accessible using the More info button on the dashboard widget tile.

Refer to these examples of the view element usage:

Configure policy rules in object collections

You can see the basic configuration for object collections in Object Collections and Views Configuration. For dashboards, use policyRule with policyThreshold to define a policySituation.

Below is an object collection for resources that are up. The collection contains a policy rule that is triggered by a situation when the amount of resources that are up drops below 99.9% of all resources.

Example Object Collection

View on GitHub

<objectCollection xmlns="http://midpoint.evolveum.com/xml/ns/public/common/common-3"
                  xmlns:q="http://prism.evolveum.com/xml/ns/public/query-3"
                  xmlns:c="http://midpoint.evolveum.com/xml/ns/public/common/common-3"
                  oid="15de186e-1d8c-11e9-a469-8f5d9cfc0259">
    <name>Resources Up</name>
    <assignment>
        <policyRule>
            <policyConstraints>
                <collectionStats>
                    <collection>
                        <interpretation>explicit</interpretation>
                    </collection>
                </collectionStats>
            </policyConstraints>
            <policySituation>#resourceHealthDanger</policySituation>
            <policyThreshold>
                <highWaterMark>
                    <percentage>99.9</percentage>
                </highWaterMark>
            </policyThreshold>
        </policyRule>
    </assignment>
    <type>ResourceType</type>
    <filter>
        <q:text>operationalState/lastAvailabilityStatus = 'up'</q:text>
    </filter>
    <domain>
        <collectionRef oid="00000000-0000-0000-0001-000000000006" type="c:ObjectCollectionType"/>
    </domain>
</objectCollection>

The example above contains an explicit definition of the collection domain. In the case here, the domain contains all the resources in the environment, and the filter clause specifies that only those that are up should be counted. The policy rule then computes the ratio of up resources to all resources and fires a situation if the ratio drops below the highWaterMark value.

This example uses policyRule with policySituation which can be leveraged for the variation of widget presentation. When the policyThreshold is met, the policySituation from policyRule can trigger the widget variation.

The policyThreshold has two important variables: lowWaterMark and highWaterMark:

  • lowWaterMark is the lower bound of the threshold, representing the lowest value for which the policy rule is activated. The policy rule triggers for all values above this value up to the highWaterMark value (closed interval).

    • If no lowWaterMark is specified, the policy rule activates for all values lower than highWaterMark.

  • highWaterMark is the upper bound of the threshold, representing the highest value for which the policy rule is activated. The policy rule triggers for all values between lowWaterMark and highWaterMark (closed interval).

    • If no highWaterMark is specified, the policy rule activates for all values greater than or equal to the lowWaterMark.

A policy rule with a threshold and no water marks will never activate.

Both watermark objects are of the WaterMarkType type and can contain count and percentage variables.

See also

Compliance

This feature is related to the following compliance frameworks:

Was this page helpful?
YES NO
Thanks for your feedback