Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.


Warning
titleEXPERIMENTAL

This feature is experimental. It means that it is not intended for production use. The feature is not finished. It is not stable. The implementation may contain bugs, the configuration may change at any moment without any warning and it may not work at all. Use at your own risk. This feature is not covered by midPoint support. In case that you are interested in supporting development of this feature, please consider purchasing midPoint Platform subscription.


Info
titleMidPoint 4.0 and later


Table of Contents

For basic information about feature please see Customizable Dashboards and Dashboards, Widgets and Reports Design Notes.

Here we describe configurable dashboard and report, which is generated from a dashboard.

For whole sample please see dashboard-system-status.

Dashboard

Dashboard is new object in midpoint, which contains name, display with label and widgets.

Code Block
languagexml
<dashboard>
     <name>system-status-dashboard</name>
     <display>
         <label>System Status Dashboard</label>
     </display>
     <widget>
         ...
     </widget>
     <widget>
         ...
     </widget>
     ...
</dashboard>

We have two kinds of widgets, widget for objectCollection and widget for objectType.

Widget

Widget contains three basic variable.

display

Display properties of the widget. Variables:

NameTypeDescription
labelStringDisplayed name of Widget.
color
StringDefaul color for widget.
icon -> cssClass
String
CssClass for widget icon for example "fa fa-user".
cssStyleStringCssStyle for widget for example "color: #444 !important" for change of font color.

data

Data which widget display. We have two kinds of data for objectCollection or for objectType. Variables:

NameTypeDescription
sourceType
DashboardWidgetSourceTypeType

Type of widget content data source. It is an identifier that specifies the type of the information (content) of the widget. This specifies type of data source for the widget content. This is enumeration type and posible values is  objectCollection (content of widget is based on object collection), auditSearch (content of the widget will be based on data from special object collection with audit trail search) and object (content of the widget will be based on data from a single object)

collection
CollectionRefSpecificationType
Specification of an explicit or implicit object collection that will be used as data source for the view.  Contains variable collectionRef, which is reference to object collection is displayed in widget.
objectRef
ObjectReferenceType

Specification of a single object as a widget data source.

Example of widget data source for object collection:

Code Block
languagexml
<data>
    <sourceType>objectCollection</sourceType> <!-- or 'auditSearch' -->
    <collection>
        <collectionRef oid="15de186e-1d8c-11e9-a469-8f5d9cfc0259" type="c:ObjectCollectionType"/>
    </collection>
</data>

Example of widget data source for object type:

Code Block
languagexml
<data>
    <sourceType>object</sourceType>
    <objectRef oid="00000000-0000-0000-0000-000000000005" type="c:TaskType"/>
</data>

presentation

Presentation define how will be data presented. We define four basic kind of presentation percentage (50%), separated with slash (5/10), separated with "of" (5 of 10) and only value (5).  Presentation contains three variables. First is dataField, which is properties of a specific widget data field. Note that the order of dataField elements is NOT significant. The field order is given by specific presentation style. Variables for dataField:

NameTypeDescription
fieldType
DashboardWidgetDataFieldTypeType

Type of the field. We support value 'value' and 'unit' now. 'value' is data field, which define displaying basic information, so number. "unit" define units for number.

expression
ExpressionType

Expression that produces value to display in the field.

For fiedType "value", we define new type of expression ProportionalExpressionEvaluatorType "proportional" with variable style. Variable style is enumeration type with value "percentage" (for example 50%), "value-slash-domain" (for example 5/10), "value-of-domain" (for example 5 of 10) and "value-only" (for example 5). 

Next presentation variable is variation. Conditional variation in the way how the widget is displayed. Variations may change colors or icons of the widget based on a condition. Variables for variation:

NameTypeDescription
condition
ExpressionType

Condition for the variation. The variation will be active if the condition evaluates to true.

display
DisplayType
Display properties to apply in case that the condition is true. Those display properties specify only those presentation aspects that are different from the usual presenation. This is supposed to be merged with the primary display properties of the widget. E.g. if the variation only changes widget color, only color needs to be specified here. Icon and other styles are taken from the primary widget display properties.

Condition can get three variables:

NameTypeDescriptionsourceType in data of widget
proportional
IntegerStatType

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

objectCollection, auditSearch
policySituations
Collection<String>Colection of policy situations.objectCollection
object
base on displayed object in widgetProcessed object.object

Last variable of presentation is view, this variable is processed for report and we will look on it below. 

Example of presentation:

Code Block
languagexml
<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>

Object Collection

You can see basic configuration for objectCollection on Object Collection.  For dashboard we can use policyRule with policyTreshold for define some policySituation. Example of object collection for resource, which have status UP:

Code Block
languagexml
<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:equal>
            <q:path>operationalState/lastAvailabilityStatus</q:path>
            <q:value>up</q:value>
        </q:equal>
    </filter>
    <domain>
        <collectionRef oid="00000000-0000-0000-0001-000000000006" type="c:ObjectCollectionType"/>
    </domain>
</objectCollection>

Variable domain is a set of object that is "all the things" for this collection. For example collection of "up resources" will have a domain "all resources". In this example we use policyRule with policySituation, which we can check in variation of widget presentation. When policyTreshold is met policySituation from policyRule is presented in variation. policyThreshold have two important variables for us, lowWaterMark and highWaterMark

lowWaterMark is lower bound of the threshold. Lowest value for which the policy rule is activated. The policy rule will be triggered for all values starting from this value up until the high water mark (closed interval). If no low water mark is specified then the policy rule will be activated for all values up to the high water mark. Policy rule with a threshold that does not have any water marks will never be activated.

highWaterMark is upper bound of the threshold. Highest value for which the policy rule is activated. The policy rule will be triggered for all values starting from low water mark up until this value (closed interval). If no high water mark is specified then the policy rule will be activated for all values that are greater than or equal to high water mark.

Both variables are WaterMarkType type, which contains variables count and percentage.

We have special object collection for widget, which use audit records.


Code Block
languagexml
<objectCollection xmlns="http://midpoint.evolveum.com/xml/ns/public/common/common-3"
				  oid="16be4077-53fd-4ada-b0cc-572318e855f5">
    <name>Error audit record</name>
    <auditSearch>
        <recordQuery>from RAuditEventRecord as aer where aer.outcome=3 and aer.eventStage=1</recordQuery>
        <domainQuery>from RAuditEventRecord as aer where aer.eventStage=1</domainQuery>
        <interval>P1D</interval>
    </auditSearch>
</objectCollection>


Object collection for audit records variable auditSearch and it have variables:

NameTypeDescription
recordQuery
String
SQL query for audit records. Defines which audit records belong to the collection.
domainQuery
String
SqlQuery for audit records.  Defines a set of object that is "all the things" for this collection. 
interval
String
Defines what old records will be displayed.

View

When we create new dashboard, than we can see it in midpoint gui. Next screenshot is displayed dashboard-system-status.

 

Report

You can generated HTML report from dashboard. Next code show how do it.

Code Block
languagexml
<report>
    <name>System Status Dashboard report</name>
    <reportEngine>dashboard</reportEngine>
    <dashboard>
        <dashboardRef oid="--OID OF DASHBOARD--" >
        </dashboardRef>
    </dashboard>
</report>

For report is important view variable in widget presentation. Specifies a view for report of an object collection that is the result of the widget. Defines columns of table in report. When we don't use view, report will be contained default columns.  

Warning

Definition of view is EXPERIMENTAL. It works only for some case, some parts are hardcoded, untested or do not even work at all. Use at your own risk. But it is perhaps best not to use this at all until the code stabilizes.


For whole sample please see dashboard-system-status.