This widget displays a box with the last available value of a metric or a statistic.
For instance, you can display the current value of a temperature metric.
Layouts
Within a gauge, you can change the background color, and icon, choosing between a Font Awesome icon or, a static icon published to an HTTP address.
In the alternative, you can change also the box layout, choosing between:
| Small Box | Info Box |
|
|
Metric Data Aggregation
In addition to showing the current metric value, the gauge can aggregate values, also on multiple things and within a time period.
For instance, within a location details page, you can display the total number of pieces produced by the machine, under the location, for a certain period.
The supported aggregations are:
- AVG: Displays the average value which can be relative in case a period has been defined or absolute considering all the available data. In the case of multiple things, the average is computed among all things.
- DELTA: Displays the variation of a metric within a period. In the case of multiple things, the resulting deltas are summed up. In case the period is not defined, the delta is computed over all the available data.
- DELTA_AVG_DAYS_1: Displays the average of the daily deltas in a period. In the case of multiple things, the daily deltas are summed up by day. In case the period is not defined, the average is computed over all the daily deltas.
- MIN: Displays the minimum value which can be relative in case a period has been defined or absolute considering all the available data. In the case of multiple things, the minimum is computed among all things.
- MAX: Displays the maximum value which can be relative in case a period has been defined or absolute considering all the available data. In the case of multiple things, the maximum is computed among all things.
Value Comparison
You can use the gauge to display the value increment with respect to the previous value.
In input to the gauge, it is possible to provide a dynamic period, by using a page period field, or a static period hardcoded into the template (e.g. THIS_MONTH). When the value increment is enabled, the gauge computes the value for the previous period and displays the increment.
The increment can be displayed as a percentage or as an absolute value. Moreover, within the same box, you can also display the value relative to the previous period.
The following gauge displays the consumption of energy during this month (DELTA over the Energy metric), the consumption of the previous month, the absolute increment, and the relative percentage.
Here is the same gauge with a different layout
The increment can be displayed differently depending on whether it is a negative or a positive thing.
Previous period calculation logic
Based on the input period, the gauge calculates the comparison period according to this logic.
If the input period is open at the end (not yet concluded), such as TODAY, THIS_MONTH, THIS_YEAR, the comparison period takes into account the end date, for instance:
- Input Period: 01 September 2022 - 19 September 2022
- Comparison Period: 01 August 2022 - 19 August 2022
If the period identifies a whole day, month or year, the comparison considers the previous day, month, or year. In all other cases, the previous period is the input period reversed in the past, for instance:
- Input Period: 10 September 2022 - 20 September 2022
- Comparison Period: 01 September 2022 - 10 September 2022
code_blocksDesign View
In the template editor, you can find the Gauge icon 
You can drag the widget into the grid and then configure the following sub-elements according to your needs:
Below are references to the properties that can be configured for this widget.
For more details on how to manage metrics, you can refer to this article.
Below are references to the properties that can be configured for this widget.
For more details on how to manage statistics, you can refer to this article.
Below are references to the properties that can be configured for this widget.
For more details on how to manage composite parts, you can refer to this article.
code_blocksCode View
Template Syntax
Below you can find some examples of how to use the component within a template.
Example 1
Gauge displaying the current value of running hours.
<gauge-widget iconName="fa-clock-o">
<metric name="Running Hours" filter="millisToHours"></metric>
</gauge-widget>
Example 2
Gauge displaying the number of pieces produced in a selected period from a set of things.
<period-field></period-field>
<things-filter-field id="machinesFilter"></things-filter-field>
<gauge-widget aggregation="DELTA"
periodRef="period"
queryFieldRef="machinesFilter"
showIncrement="RELATIVE">
<metric name="thing.Total Pieces"></metric>
</gauge-widget>
Component Reference
Here is a comprehensive list of all the elements and properties that can be used to configure the component.
| Gauge <gauge-widget> | |
|---|---|
| PROPERTIES | |
| Aggregation | Indicates whether to render the last value or the aggregated value. Type: ENUM | Optional | Values: LAST_VALUE AVG DELTA DELTA_AVG_DAYS_1 MIN MAX aggregation="AVG" |
| Background Color Class | The class applied on the background, refer to the Bootstrap Colors guide Type: STRING | Optional backgroundColorClass="fooBar" |
| CSS Class | The name(s) of the CSS class used to customize the widget layout. Type: STRING | Optional class="my-custom-class" |
| Icon Name | The name of the Font Awesome icon. Type: STRING | Optional iconName="fa-thermometer" |
| Icon Url | The URL where the icon to display is located. Type: STRING | Optional iconUrl="fooBar" |
| Increment Value Position | Indicates whether to place the increment value Type: ENUM | Optional | Values: RIGHT BOTTOM incrementValuePosition="BOTTOM" |
| Layout | Indicates the rendering layout Type: ENUM | Optional | Values: INFO_BOX SMALL_BOX layout="SMALL_BOX" |
| Measure Unit Position | Indicates where to place the unit of measurement. Type: ENUM | Optional | Values: NONE METRIC_NAME_RIGHT METRIC_VALUE_RIGHT measureUnitPosition="METRIC_NAME_RIGHT" |
| Null Increase Class | The CSS class customizing how to render a null variation (e.g. text-gray) when the increment value si displayed. Type: STRING | Optional nullIncreaseClass="fooBar" |
| Period | The default period to use when computing DELTA. Type: ENUM | Optional | Values: LAST_24H LAST_7_DAYS LAST_30_DAYS THIS_MONTH THIS_YEAR period="LAST_7_DAYS" |
| Period Variable | The id of the page's variable providing the date range filtering period, for instance the id of a <period-filter-field>. Type: STRING | Optional periodRef="period" |
| Query Variable | The id of the page's <things-filter-field> used for searching. Type: STRING | Optional queryFieldRef="query-1" |
| Show Increment | Indicates whether the increment value should be calculated from the previous time period. Type: ENUM | Optional | Values: NONE ABSOLUTE PERCENTAGE ABSOLUTE_AND_PERCENTAGE showIncrement="ABSOLUTE" |
| Show Last Update | The flag indicating whether to show or hide the last update timestamp. Type: BOOLEAN | Optional | Values: true false [showLastUpdate]="true" |
| Show Previous Value | Indicates whether the previous value must be displayed on the right of the current one. Type: BOOLEAN | Optional | Values: true false [showPreviousValue]="true" |
| Title | The title displayed on the top part of the widget box. Type: STRING | Optional [title]="'Details'" |
| Value Decrease Class | The CSS class customizing how to render a negative variation (e.g. text-red) when the increment value si displayed. Type: STRING | Optional valueDecreaseClass="fooBar" |
| Value Increase Class | The CSS class customizing how to render a positive variation (e.g. text-green) when the increment value si displayed. Type: STRING | Optional valueIncreaseClass="fooBar" |
| Visibility Condition | The expression that allows you to reduce the visibility of the element. Type: STRING | Optional *ngIf="getUser().organizationId != null" |
| End Date Variable | The <period-field>'s End Variable filtering data by end date. Type: STRING | Optional endDateFieldRef="toDate" [DEPRECATED] Use the Period Variable property. |
| Start Date Variable | The <period-field>'s Start Variable filtering data by start date. Type: STRING | Optional startDateFieldRef="fromDate" [DEPRECATED] Use the Period Variable property instead. |
| SUB-ELEMENTS | |
| Metric | The metric whose current value must be displayed within the gauge box. Single | Required <metric name="Temperature"></metric> |
| Statistic | The statistic whose value must be displayed within the gauge box. Single | Required <statistic name="alertCount" resource="ALERT"></statistic> |
| Composite Part | The widget part combining multiple properties and metrics. Multiple | Optional <composite-part> <metric name="Temperature"></metric> <metric name="Humidity"></metric> <property name="properties.type"></property> </composite-part> |
| Metric <metric> | |
|---|---|
| PROPERTIES | |
| Filter | The name of the filter used to transform and display values. Type: FILTER | Multiple value | Optional filter="fooBarFilter" |
| Label | The metric alternative label. Type: STRING | Optional label="Temperature" |
| Name | The metric whose value(s) must be loaded by the widget. Type: METRIC | Required name="Temperature" |
| Unit | The unit of measurement to be displayed along the value. Type: STRING | Optional unit="°C" |
| Visibility Condition | The expression that allows you to reduce the visibility of the element. Type: STRING | Optional *ngIf="getUser().organizationId != null" |
| Statistic <statistic> | |
|---|---|
| PROPERTIES | |
| Aggregation | The function used to aggregate data. Type: ENUM | Optional | Values: AVG COUNT MAX MIN SUM aggregation="MAX" |
| Alert Status | Define whether to include alerts that are still active, or have been activated in a period. Type: ENUM | Optional | Values: ACTIVE ACTIVATED activationType="ACTIVATED" |
| Averaged By | The count used to average the statistic results (e.g. Average alert count by thing). Type: ENUM | Optional | Values: thingCount averagedBy="thingCount" |
| Group By | The property used to group results. For instance: customer.country. In the case where the underlying objects are temporally distributed you can also aggregate by HOUR, DAY, MONTH and YEAR. Type: GROUP_BY | Optional groupBy="customer.name" |
| Max Result Count | The number of maximum returned results (default all results are returned). Type: INTEGER | Optional [limit]="123" |
| Property | The object property whose values must be aggregated. Type: PROPERTY | Optional property="PROPERTY" |
| Query | The array of conditions filtering out items. For instance: [query]='[{'property': 'connectionStatus', 'predicate': 'eq', 'value': '1'}]' Predicates: eq, beginsWith, like, notLike, isEmpty, isNotEmpty, gt, gte, lt, lte. Type: QUERY | Optional query="[{'property': 'connectionStatus', 'predicate': 'eq', 'value': '1'}, {...}]" |
| Resource | The resource from which to retrieve the items to be used to calculate the statistic. Type: ENUM | Required | Values: ACTION ALERT CUSTOMER LOCATION PARTNER THING USER WORK_SESSION resource="ALERT" |
| Sorting | The sort direction used to order categories by value (default none). Type: ENUM | Optional | Values: ASC DESC sortDirection="DESC" |
| Value Filter | The name of the filter used to transform and display values. Type: FILTER | Optional filter="fooBarFilter" |
| Alert Category | The alert category used to filter the statistic results. Type: ENUM_ARRAY | Optional | Values: INFORMATION ADVICE ANOMALY FAILURE SAFETY [category]="['ANOMALY', 'FAILURE']" [DEPRECATED] Define a condition into the query property |
| Alert Severity | The alert severity used to filter the statistic results. Type: ENUM_ARRAY | Optional | Values: INFORMATIONAL WARNING CRITICAL EMERGENCY [severity]="['WARNING', 'CRITICAL']" [DEPRECATED] Define a condition into the query property. |
| End Date Variable | The <period-field>'s End Variable filtering data by end date. Type: STRING | Optional endDateFieldRef="toDate" [DEPRECATED] Use the Period Variable property. |
| Include Zero Values | The flag indicating whether to include or not the alerts with zero occurrences. Type: BOOLEAN | Optional | Values: true false [includeZeroValues]="true" [DEPRECATED] This feature is no longer supported. |
| Name | The statistic whose results(s) must be loaded by the widget. Type: STATISTIC | Required | Values: activeAlertCount activatedAlertCount alertCount alertCountByAlertDefinition thingCount thingPropertyAggregation locationCount customerCount userCount workSessionCount workSessionCount workSessionElapsedTime workSessionSumMetricValues name="alertCount" [DEPRECATED] Use the Resource, and select the Aggregation and Property to aggregate. |
| Period Variable | The id of the page's variable providing the date range filtering period, for instance the id of a <period-filter-field>. Type: STRING | Optional periodRef="period" [DEPRECATED] Use the Period Variable property on the widget. |
| Start Date Variable | The <period-field>'s Start Variable filtering data by start date. Type: STRING | Optional startDateFieldRef="fromDate" [DEPRECATED] Use the Period Variable property instead. |
| Sum Metric | The work-session monitored metric to sum. Type: STRING | Optional sumMetric="metrics.Pieces.DELTA" [DEPRECATED] Use the Resource property and select the Aggregation and the Property to aggregate. |
| Thing Definition | The name of the thing-definition used to filter the statistic results. Type: STRING | Optional thingDefinition="fooBar" [DEPRECATED] Define a condition into the query property |
| Composite Part <composite-part> | |||||
|---|---|---|---|---|---|
| PROPERTIES | |||||
| Filter | The filter applied on the composite-part to transform or display its value. Type: FILTER | Optional filter="fooBarFilter" |
||||
| Label | The label displayed by the widget. Type: STRING | Optional label="fooBar" |
||||
| Name | The composite-part name. Type: STRING | Optional name="fooBar" |
||||
| Visibility Condition | The expression that allows you to reduce the visibility of the element. Type: STRING | Optional *ngIf="getUser().organizationId != null" |
||||
| SUB-ELEMENTS | |||||
| Metric | The metric whose value must be loaded within the composite-part. Multiple | Optional <metric name="Temperature"></metric>
|
||||
| Property | The property whose value must be loaded within the composite-part. Multiple | Optional <property name="serialNumber"></property>
|
||||
Comments
0 comments
Please sign in to leave a comment.