|
Dashboard feature
This page describes configuration of Dashboard midPoint feature.
Please see the feature page for more details.
|
Use the configuration options described here to customize your 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. |
The data element defines the source of the data that the widget displays.
The table below contains more details about the configuration options you have regarding the data sources.
| Name | Type | Description |
|---|---|---|
|
|
Specify the type of input data for generating a message shown in the widget. Possible options are:
|
|
|
Use this element in asynchronous widgets to select the data source the widget uses for displaying data. For asynchronous widgets, set this to The widget in the GUI usually contains a More info button which takes users to a details page with objects queried using the Refer to the simple example of |
|
|
Specify which object collection should the widget use to query midPoint objects.
The element contains a |
|
|
Specifies a single object as a data source for the widget. |
|
|
Specifies a string as a widget data source. The string can be stored by a report task. Use this configuration for asynchronous widgets. |
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="ObjectCollectionType"/>
</collection>
</data>
</widget>Below is a bare-bones asynchronous widget that uses an object collection as its data source. See Create asynchronous widget to reduce system load for the required configuration regarding asynchronous widgets.
<widget>
...
<data>
<sourceType>objectCollection</sourceType> (1)
<displaySourceType>widgetData</displaySourceType> (2)
<collection>
<collectionRef oid="15de186e-1d8c-11e9-a469-8f5d9cfc0259" type="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.
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.
<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:
To create a dashboard widget that uses audit log entries as a source, you need to create a collection for the audit log records.
You need to use the auditSearch option as the sourceType of the widget instead of objectCollection.
<widget>
<identifier>modified-users</identifier>
<display>
<label>during the past week</label>
<color>#265DA6</color>
<icon>
<cssClass>fa fa-user-pen</cssClass>
</icon>
</display>
<data>
<sourceType>auditSearch</sourceType> (1)
<collection>
<collectionRef oid="e45dc8a1-5782-4fd0-a4b4-952749030a9f" relation="org:default" type="c:ObjectCollectionType"> (2)
<!-- Audit log - modified users - last 7 days -->
</collectionRef>
</collection>
</data>
<presentation>
<dataField>
<fieldType>value</fieldType>
<expression>
<proportional>
<style>value-only</style>
</proportional>
</expression>
</dataField>
<dataField>
<fieldType>unit</fieldType>
<expression>
<value>users modified</value>
</expression>
</dataField>
</presentation>
</widget>| 1 | The auditSearch source type signifies that the collection contains audit log events instead of the "usual" midPoint objects. |
| 2 | A reference to a collection that filters the audit log events for the widget to display. |
You can create a simple user statistics dashboard like the one below by creating object collections for various events happening to user objects and connecting them to one dashboard. See the guide on audit log collection configuration for details.
When you click the More info button, you get redirected to the filtered audit log where you can inspect the records in more detail.
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.
The display attribute contains configuration of the widget visual side in the GUI.
| Name | Type | Description |
|---|---|---|
|
|
Displayed name of widget. |
|
|
Default background color of the widget. |
|
|
CSS class for widget icon; e.g., |
|
|
CSS style for the widget; e.g., |
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).
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:
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.
<dashboard xmlns:c="http://midpoint.evolveum.com/xml/ns/public/common/common-3"
xmlns:icfs="http://midpoint.evolveum.com/xml/ns/public/connector/icf-1/resource-schema-3"
xmlns:org="http://midpoint.evolveum.com/xml/ns/public/common/org-3"
xmlns:q="http://prism.evolveum.com/xml/ns/public/query-3"
xmlns:ri="http://midpoint.evolveum.com/xml/ns/public/resource/instance-3"
xmlns:t="http://prism.evolveum.com/xml/ns/public/types-3"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://midpoint.evolveum.com/xml/ns/public/common/common-3"
oid="0d0e7151-8a8c-4228-a1f1-fb09ced85133">
<name>dashboard-users</name>
<display>
<label>Archived users presented in different styles</label>
</display>
<!-- The number of objects in the collection without showing the collection domain -->
<widget>
<identifier>archive-users-percentage</identifier>
<display>
<label>Number archived users</label>
<color>#FF9B05</color>
<icon>
<cssClass>fa fa-user-lock</cssClass>
</icon>
</display>
<data>
<sourceType>objectCollection</sourceType>
<collection>
<collectionRef oid="a0c7fa21-2b0a-4a78-9de6-39acf9a79dcd" type="c:ObjectCollectionType" />
</collection>
</data>
<presentation>
<dataField>
<fieldType>value</fieldType>
<expression>
<proportional>
<style>value-only</style>
</proportional>
</expression>
</dataField>
<dataField>
<fieldType>unit</fieldType>
<expression>
<value>archived users</value>
</expression>
</dataField>
</presentation>
</widget>
<!-- The percentage of collection domain objects matching the specified object collection criteria -->
<widget>
<identifier>archive-users-percentage</identifier>
<display>
<label>Percentage of archived users</label>
<color>#265DA6</color>
<icon>
<cssClass>fa fa-user-lock</cssClass>
</icon>
</display>
<data>
<sourceType>objectCollection</sourceType>
<collection>
<collectionRef oid="a0c7fa21-2b0a-4a78-9de6-39acf9a79dcd" type="c:ObjectCollectionType" />
</collection>
</data>
<presentation>
<dataField>
<fieldType>value</fieldType>
<expression>
<proportional>
<style>percentage</style>
</proportional>
</expression>
</dataField>
<dataField>
<fieldType>unit</fieldType>
<expression>
<value>of users archived</value>
</expression>
</dataField>
</presentation>
</widget>
<!-- The slash notation: "X/Y" where X is the collection object count and Y is the collection domain -->
<widget>
<identifier>archived-users-value-slash-domain</identifier>
<display>
<label>Number of archived users</label>
<color>#767171</color>
<icon>
<cssClass>fa fa-user-lock</cssClass>
</icon>
</display>
<data>
<sourceType>objectCollection</sourceType>
<collection>
<collectionRef oid="a0c7fa21-2b0a-4a78-9de6-39acf9a79dcd" type="ObjectCollectionType"/>
</collection>
</data>
<presentation>
<dataField>
<fieldType>value</fieldType>
<expression>
<proportional>
<style>value-slash-domain</style>
</proportional>
</expression>
</dataField>
<dataField>
<fieldType>unit</fieldType>
<expression>
<value>users archived</value>
</expression>
</dataField>
</presentation>
</widget>
<!-- The "of" notation: "X of Y" where X is the collection object count and Y is the collection domain -->
<widget>
<identifier>archived-users-value-of-domain</identifier>
<display>
<label>Number of archived users</label>
<color>#14205F</color>
<icon>
<cssClass>fa fa-user-lock</cssClass>
</icon>
</display>
<data>
<sourceType>objectCollection</sourceType>
<collection>
<collectionRef oid="a0c7fa21-2b0a-4a78-9de6-39acf9a79dcd" type="ObjectCollectionType"/>
</collection>
</data>
<presentation>
<dataField>
<fieldType>value</fieldType>
<expression>
<proportional>
<style>value-of-domain</style>
</proportional>
</expression>
</dataField>
<dataField>
<fieldType>unit</fieldType>
<expression>
<value>users archived</value>
</expression>
</dataField>
</presentation>
</widget>
</dashboard>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.
| Name | Type | Description |
|---|---|---|
|
|
Condition for the variation. The variation activates when the condition evaluates to true. |
|
|
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:
| Name | Type | Description | sourceType in data of widget |
|---|---|---|---|
|
|
Integer stat (statistic) entry. This entry contains stat value, together with domain value. |
|
|
|
Collection of policy situations |
|
|
Based on the displayed object in the widget |
Processed object |
|
|
|
Data stored in the widget |
|
<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>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:
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.
<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.
This feature is related to the following compliance frameworks:
ISO/IEC 27001 5.2: Information security roles and responsibilities
ISO/IEC 27001 5.8: Information security in project management
ISO/IEC 27001 5.9: Inventory of information and other associated assets
ISO/IEC 27001 5.26: Response to information security incidents
ISO/IEC 27001 5.36: Compliance with policies, rules and standards for information security