A widget is an element that displays a specific type of information or functionality on a dashboard. Widgets are used to display data, visualize information obtained from devices and to control the devices connected to the OCS360 platform.
Helpful Links
Adding a Widget to the Dashboard
There are five types of widgets:
-
Timeseries Widgets - display data for a specific time window. It can be either Realtime - the dynamically changed time frame for a certain latest interval, or History - a fixed historical time frame. An example of a Timeseries Widget are chart widgets.
-
Latest Values Widgets - displays the latest values of attributes or timeseries keys. For example, the device model or latest temperature reading.
-
Control Widgets- allow you to send RPC commands to your devices. For example, control desired temperature on the thermostat device.
-
Alarm Widgets - allow you to display alarms.
-
Static Widgets - designed to display static data. For example, a floor plan or static company information.
Each widget typically has specific settings and parameters that allow users to customize its behaviour and appearance according to their needs.
This guide covers main concepts and various widget settings.
Adding a Widget to the Dashboard
To add a new widget to a dashboard, follow these steps:
-
Open your dashboard and enter edit mode.
-
Click the "+ Add widget" icon at the top of the screen or click a large "Add new widget" sign in the middle of the screen to open the Select widgets bundle dialog window.
-
Select a widget bundle, such as "Charts". To quickly find the desired widget, use the search bar by clicking the magnifying glass icon and entering the name of the widget.
-
Choose a widget, for instance, "Timeseries Line Chart" and click on it to open the "Add Widget" dialog window.
-
Specify the data source, add the data key, and click the "Add" button. Finally, apply the changes.
-
The first widget has been created.
Widget settings consist of one or multiple data sources, appearance settings, widget card settings, actions, and mobile appearance that the user can customize and perform on the widget’s content.
NOTE: Only the data source configuration is strictly required. User can leave all other configuration tabs with the default values in most of the cases
During widget creation, the user can choose between basic and advanced functionality. Switching between modes is done in the top right corner of the widget creation window.
Basic Functionality
Basic functionality is suitable for a quick start when a single data source type is used without additional conditions or filters. It includes settings for the Time Window, datasource selection (entity alias or device), and a basic set of settings for the appearance of widgets, which depends on the widget’s purpose.
Advanced Functionality
In the advanced functionality, the user can use multiple datasources (if supported by the widget), and apply filters. And it includes five tabs for more detailed widget configuration: Data, Appearance, Widget cards, Actions and Mobile.
Additionally, in the advanced functionality, there are additional datasource types available: Function, Entities Count and Alarms Count (these data types are not supported by all widgets)
Widget Time Window
A Widget TimeWindow defines a time interval and aggregation function that should be used to send the time series or alarm data. By default, every widget uses the main Time Window determined in the dashboard’s toolbar. The user can overwrite the default Time Window by toggling the option to “Use widget Time Window” parameter. The user can also hide the Time Window selection for a specific widget from the user using the “Display Time Window” checkbox.
Data Source Types
Widget data settings are for adding one or multiple data sources. A data source is a combination of a data source type, an entity alias, an optional filter and list of data keys (entity time series). Basically, the data source determines which entities (alias and filter) widget should use and what data keys to fetch for those entities.
-
There are three main types of data sources: Device, Entity, and Function.
-
Additionally, for some widgets (such as the Value card), there are additional data source types, such as Entities count and Alarms count.
The following contains a discussion of each type.
Device as the Datasource
Specifying a device as the data source retrieves data from the specified device.
For example, let’s assume the user has a device that publishes temperature values and wants to display this data on a widget. Let’s visualize this data using the Thermometer scale widget.
-
Open the dashboard and enter Edit Mode. Then click the "+ Add widget" icon at the top of the screen or click a large "Add new widget" sign in the middle of the screen to open the "Widgets Bundle” dialog window.
-
Select "Analog Gauges" widget bundle.
-
Then select a "Thermometer scale" widget.
-
The "Add Widget" dialog window will open. Select data source type - "Device" and select the device. Then add the data key. Click "Add" and save all changes.
-
Thermometer scale widget is created.
NOTE: In this case the data source can only be a single device.
Function as the Datasource
Function as the Data Source is used when the user does not have any data but wants to test a widget visualization.
-
Open the dashboard and enter Edit Mode. Then click the "+ Add widget" icon at the top of the screen or click a large "Add new widget" sign in the middle of the screen to open the "Widgets Bundle” dialog window.
-
Select a "Cards" widget bundle.
-
Then select a "Value Card" widget.
-
The "Add Widget" dialog window will open. Navigate to the advanced functionality and select data source type - "Random". Then add a function - "Random" and click the "pencil" icon of the "Random" key to open the data key configuration window.
-
Change the label name to "temperature" and specify the units. Click "Save".
-
Click "Add" and save all changes.
-
This will have created the value card widget which displays random value.
Entities Count
The Entities Count allows the user to visualize the number of entities by displaying them on a widget and thus determine the number of devices, assets, etc.
For example, displaying the total number of existing devices on the widget.
-
Open the dashboard and enter Edit Mode. Then click the "+ Add widget" icon at the top of the screen, or click a large "Add new widget" sign in the middle of the screen to open the "Widgets bundle” dialog window
-
Select a "Cards" widget bundle
-
Then select a "Value card" widget
-
The "Add Widget" dialog window will open. Go to the advanced functionality and select the data source type - "Entities Count". Now, you need to create a new entity alias. Click the "Create new" button in the entity alias row
-
In the opened "Add alias" dialog, enter an alias name, select filter type - "Entity type", and choose an entity type - "Device". Click "Add"
-
In the Data key row click the "pencil" icon of the "count" key to open the data key configuration window
-
Change the label name to "Devices Count" and specify units. Click "Save"
-
Finally, click "Add" and save all changes
-
This will create a widget that displays the number of existing devices.
Alarms Count
The Alarms Count allows user to display the total number of alarms from all configured devices on a widget.
For example, displaying the total number of existing alarms on the widget.
-
Open the dashboard and enter Edit Mode. Then click the "+ Add widget" icon at the top of the screen, or click the large "Add new widget" sign in the middle of the screen to open the "Widgets Bundle” dialog window
-
Select "Cards" widget bundle
-
Then select a "Value card" widget
-
The "Add Widget" dialog window will open. Go to the advanced functionality, select the data source type - "Alarms count" and specify filters. In the Data key row click the "pencil" icon of the "count" key to open the data key configuration window
-
Change the label name to "Alarms Count" and specify units. Click "Save"
-
Finally, click "Add" and apply changes
-
This will create a widget that displays all alarms of existing devices
Data Keys define time series, attribute or entity field that you would like to use in the widget. Data Keys consist of type (time series, attribute of entity field) and the actual key.
The list of available attribute keys is basically a list of all client, server and shared attributes of the device or other entity. The list of available time series keys depends on what time series data the selected devices send to the OCS360 platform or what time series data the user has saved via the Rule Engine.
The list of entity fields depends on the entity type and may extend in the future:
-
Devices, assets and entity views - include the following fields: create time, entity type, name, type, label, additional info.
-
User - has the following fields: created time, first name, last name, email and additional info.
-
Customer - has the following fields: create time, entity type, email, title, country, state, city, address, zip code, phone, additional info.
The Data Keys list for the data source depends on the widget type:
-
Timeseries Widgets - allows for choosing time series data keys. Additionally, the user can configure the Time Window.
-
Latest Values Widgets - allows for choosing time series, attributes and entity fields;
-
Static and Control Widgets - do not require a data key.
-
Alarm Widgets - allows for choosing all data keys: time series, attributes, entity and alarm fields. Additionally, the user can configure the Time Window and alarm filter
To add a time series or attribute key to the data source, click on the data keys row and select the desired key from the dropdown menu.
Let’s assume the user doesn’t have the required time series or attribute key in the database yet. In such a case, the user can still add a key to the data source, and the widget will start displaying the data as soon as the device will send it to OCS360 platform. To do this, click on the data key row, then enter the name and select the type of the future key: Attributes, Entity field, or Timeseries.
Within the Advanced Widget settings, the Data Key can be configured in two distinct modes: General and Advanced. Both modes offer unique configuration options.
General Data Key Configuration
The Data Key configuration varies based on the widget type and its accepted data type. In general settings, some widgets allow the user to modify the key’s name and color, adjust the label name, add a specific character next to the value (exclusive to the Timeseries key), define decimal precision, and toggle the “Use post-processing function” on or off.
If the user uses the basic functionality for adding a new widget, these settings are available in the widget creation window.
If the user uses the advanced functionality for adding a new widget, click the “pencil” icon of a key in the data keys row to open the full data key settings.
Basic Data Key Configuration
Key - Configure the Data Key for the widget. The key name can be changed to display the data as needed. In the example below, we will change the key for the time series chart
-
The timeseries chart is added with key name “Temperature”
-
To change the key name, click on the key field and select the required key
-
Click Save
-
We can see the key has been changed, the label still shows as Temperature as we have not changed that
NOTE: There are four types of Keys: Attributes, Time Series, Entity Field and Alarm Field (only for the Alarm widget). To correctly display the data, change the key name to the existing key name of the same type. If time series or attribute key are still not added in the database, the user can add the key as a data source and the widget will start displaying the data as soon as the device sends the data to the OCS360 platform.
Label
The name that gets displayed at the bottom of the Time Series Widget is the Label name.
-
Change the Label name as desired and click “Save” in the lower right corner of the dialog window.
-
Click Save and apply the changes.
Units
The user can indicate a special symbol that will be displayed next to the value. Enter the desired character in the unit’s field and click “Save”.
Decimals
Specify the desired number of digits to be displayed after the floating-point number and click “Save
Colors
Each key is assigned a different color. In some widgets (for example, Chart), the color of the graph line displayed in the widget is the color of the key. The user can change the color of the key. Click on the pencil icon in the key, select the desired color and press “Select”.
We can see the color of graph is changed as shown below.
Aggregation of Key
By default, the Latest Values widgets do not have the time window. If the user enables aggregation for any data key in the ‘Latest Values’ widgets, the time window control will appear. The user can set up aggregation for each telemetry key individually that wants to be displayed, and at the same time you do not need to store it in the database. The time window configuration is limited to the real-time intervals (Current Hour/Day/Month) and ‘History’ time intervals. The real-time intervals such as ‘last 30 minutes’ or ‘last 24 hours’ are not supported for performance reasons.
For example, in the analog gauge widget, by default the aggregation is set to none
The user can select aggregation as Minimum, Maximum, Average, count, or sum
Aggregation Options:
-
Minimum or Maximum - Selects the minimum or maximum value from the given interval. Used to detect peak negative or positive values. For example, power surges in the power cable, air pollution, equipment workload, etc.
-
Average - Calculates the average from the selected interval (Summarizes, then divides by the count of telemetry from the selected interval). For example, you can use average aggregation for weekly fuel consumption, acoustical noise in dB, rotation fan speed, signal quality, etc.
-
Sum - Summarizes all telemetry for the specified period. Aggregation, for example, uses for different types of telemetry, mileage (km), water consumption, idle time, etc.
-
Count - Calculates the total number of transmitted messages for the selected period. It can be useful in setting up and optimizing devices running on battery power or when evaluating sensor activation sensitivity, etc.
Delta Function
Allows the user to calculate the delta between aggregated values for current and relative time window intervals.
Comparison Period
Comparison Period - A parameter that takes the history interval as a basis and converts it according to the selected option. List of options below.
-
Previous Interval (default) - set as a default option, when calculating, not only time is taken into account, but also the type of interval (Current day or Current day so far, etc.)
Example: History - "Current month so far" option, suppose is interval 1.09.23 to 25.09.23 then previous interval will be 1.08.23 to 25.08.23.
-
Day Ago - from the start and end of the history interval, takes away 24 hours.
For example, with the amount of water spent Current day and Delta - Day ago
-
Week Ago - takes interval one week earlier from history interval (168 hours).
Example with average, history interval - Current day, and Week ago delta
-
Month Ago - The same interval (in days) as the history interval and subtracts from the current history interval. Example, if the current month is February (28 days) then Month ago would be the previous 28 days, not the entire previous month.
Example, with sum water, history - Current day and Delta - Month ago
-
Year Ago - Interval that was 365 days ago from the current history interval.
NOTE: If it is necessary to compare, suppose the aggregation for the previous month and the month of the past year.
-
Custom Interval - This option is for setting individual intervals. The maximum allowed value is limited to the int type. Example: 43200000 = 12 hours
Delta Calculation Result
This option allows the user to specify how the result should be displayed:
-
Previous Value - Displays the aggregation value of Compare Interval (not current history interval).
-
Delta (absolute) - Displays the difference between Compared Intervals, this option is set by default.
-
Delta (percent) - Displays the result as a percentage relative to the previous interval
Formula: (IntervalValue - prevIntervalValue)/prevIntervalValue*100
-
Use data post-processing function. The data post-processing function allows changing the output data depending on the users need. To use data post-processing function, the user must check the “Use data post-processing function” checkbox and enter the function in the field below. Then click the “Save” button in the lower-right corner.
Advanced Data Key Settings
Advanced Data Keys configuration is responsible for the visibility, style, and appearance of a specific data key column on the widget. The Charts Widget Bundle has its own unique advanced data key configuration. All other widget bundles have only basic data key configuration.
Alarm widgets allow the user to filter alarms based on status, severity and type. The user can choose a combination of alarm statuses and severity. The user can also define specific alarm types as well as enable search of propagated alarms.
Let’s assume that the user has added the “Timeseries Line Chart” widget to display Temperature using the widget data configuration steps. The user should see a similar widget (note that the device should send/simulate some data to see the actual lines in the chart)
Use the basic widget settings to customize the widget. We will demonstrate how each setting affects the widget.
Data Settings
The user can choose which symbol to display next to the value and the number of digits after the floating-point number. These settings are useful if the user wants to apply the same settings for all axis. For example, the widget configured with temperature readings for multiple devices, the user can add ‘°C’ or ‘°F’ symbol. However, if both temperature and humidity are displayed then the user must configure these data keys separately using data key settings.
The user can also specify an alternative message that will be displayed if the widget doesn’t have incoming data. When the data arrives, the message will disappear, and the incoming data will be displayed.
NOTE: These settings are available in the “Advanced” functionality, “Appearance” tab of the widget’s settings.
Common Settings
Stacking Mode
This option is relevant to the “Timeseries Bar Chart” widget. The Stacking Mode function displays the sum of the entity values to prevent overlap, with each value distinguished by a unique color. This function can be used only if the data aggregation function is not set to None. Without activating the “Enable stacking mode”, the bars will be split according to the values of the entities used. To view the values of all entities, the user needs to hover the mouse over the bar.
If the user needs to exclude a specific key from stacking, go to the advanced data key configuration, and check the “Exclude from stacking” checkbox.
Legend Settings
By default, the “Display Legend” option is enabled for chart widgets. This legend displays statistical values, including minimum, maximum, average, and total. In contrast, other widgets do not have this option enabled.
While the legend is enabled, the user has the flexibility to:
-
Choose the legend’s direction and position.
-
Select which data values to include (minimum, maximum, average, total)
-
Select to sort the data keys or keep them unsorted.
The user may notice that the legend displays the datakey label for each configured data key. When you have data from multiple devices in the same widget, it is hard to find which device corresponds to which record in the legend or in the tooltip. In order to make the legend and tooltip clear, you should use ${entityName} or ${entityLabel} in the data key configuration.
Axis Settings
Configure the preferred axis parameters.
Specify the titles of the vertical and horizontal axis and set the minimum and maximum scale values.
The user can also set the ticks color, the number of decimal places, and step size between ticks.
• Vertical Axis Settings
• Horizontal Axis Settings
Ticks Formatter Function - f(value)
For example, telemetry data that takes the values of very large numbers, especially when there is a special symbol near the values. However, we need to build a small graph (since we don’t have a lot of free space on the dashboard). Therefore, using the ticks-formatter function, we can convert the ticks values to a more compact form.
In the tick format function, enter the below code to display the axis vaues in exponential format:
return value.toExponential(1) + " C"
Chart Background Settings
The user can change the appearance of the chart grid, customize the color of the background, the grid frame, and its ticks, and turn off line visibility.
Tooltip Settings
-
Hover individual points - When the box “Hover individual points” is checked, the user won’t see value points on the lines.
-
Show cumulative values in stacking mode - While stacking mode is on, the user can check the box “Cumulative values” to enable the chart to display sums of all entity values.
-
Tooltip value format function, f(value, latestData) - is used when the user wants to manually customize the tooltip.
The user can customize the values that will be displayed in the tooltip via tooltip settings or Advanced Datakey configurations. Tooltip configuration via "Settings" is basic and applies to all entities at the same time. When configured in the Advanced Data key configuration, it is applied only to the specific time series data, and the basic tooltip function will be overwritten by this configuration.
In State Chart - the user can configure entity states to be shown on a tooltip depending on entity values.
Example, let’s use the function to convert values from Celsius to Fahrenheit and display these values side by side:
let celsiusValue = parseFloat(value).toFixed(2)
let farenheitValue = parseFloat(celsiusValue*1.8 + 32).toFixed(2)
return celsiusValue + ' °C (' + farenheitValue + ' °F)'
-
In the Tooltip value format function field, enter the tooltip function, then apply changes.
-
Hover with the mouse over the widget to see tooltip with applied value format function.
Comparison Settings
The user can show historical data with which to compare.
-
In the "Appearance" tab, toggle the "Enable comparison" checkbox and from the drop-down menu select the time to show historical data with which to compare. In the "Comparison X axis settings" section, select axis position, where the compared axis will be located on the widget. Also, the user can enter the axis title and show axis tick labels.
-
Navigate to the "Data" tab and click the “pencil” icon of a key in the data keys row
-
In the data key configuration window, navigate to the "Advanced" tab and choose the comparison line color. When the required changes for Comparison Settings configuration are done, then apply changes.
-
Since the comparison settings work only in history time window mode, click the "Edit time window" icon in the dashboard toolbar, go to the "History" tab, and select the time interval that the user wants to compare the current data with. Then click "Update" to apply.
-
Now the user can compare the value for the current minute and for five minutes ago.
Custom Legend Settings
Use the Custom Legend Settings when the user needs to showcase data that isn’t suitable for chart representation, such as specific attributes; or when the user wants to display only a certain time series in the Chart legend. For instance, consider active/inactive attributes that can be displayed in a Table widget but not on a Chart.
-
Navigate to the "Appearance" tab. Activate the "Enable Custom Legend" option to use attribute or time series values as key labels. Click on "+ Add new key". In the drop-down menu that appears, input the key name and choose the key type.
-
Proceed to the "Data" tab. Click the pencil icon next to a data key to access the Data key configuration window.
-
In the label line, input the pattern ${} and place the data key name within the brackets. Click "Save" to set the new label name and apply all changes.
-
Custom legend settings is now applied to the widget.
Widget Title Settings
The user can input a custom widget title, tooltip and title style. The user can also add an icon to the title and control icon color and size. See configuration and the corresponding result below.
Widget Style Settings
The user can customize a personal style for the widget using CSS properties. This style will be applied to the main div element of the widget.
The user can also disable the widget shadow using the “Drop shadow” checkbox and disabling fullscreen using the “Enable fullscreen” checkbox. All those settings are enabled by default.
The user can also change the background color, text color, padding, and margin. See the configuration and the corresponding result below.
For example, the style and background color of the widget are configured as below:
Widget Buttons Settings
Enable Fullscreen
The user can disable fullscreen using the “Enable fullscreen” checkbox. This setting is enabled by default.
Using this option, the widget data can be exported to .CSV file format. Users can enable this option in the widgets configuration dialog.
Note: Widget data export is not supported for control widgets, Inputs widgets, alarm and navigation widgets.
The export icon appears in the widget. Clicking the icon exports the data in the widgets to a CSV file format.
[Widget Configuration - BASIC View]
|
 |
[Widget Configuration - ADVANCED View]
|
|
A maximum of 50000 data values can be exported from the widgets. If the widget has greater than 50000 data values to export, the data from the current time to the last 50000 values will be exported.
Widget Actions allow quick and easy configuring of the transition to the created state, transferring to other dashboards, or even updating the current dashboard. Depending on the widget, the action sources differ. However, the type of action the user is able to choose will be the same for all widgets. Actions are adjusted in the Edit Mode of the needed widget.
Refer to Widget Actions: https://help.ocs360.cloud/docs/Widgets/widgetactions
With Mobile Mode Settings, the user can optimize the widget for easy viewing on mobile devices.
Additionally, the user can hide/show the widget in Mobile Mode or Desktop Mode.
Mobile Mode settings consist of two options:
-
Order - set to an integer, specifies the priority of the order of displaying widgets in mobile mode (note that in mobile mode all widgets are displayed in one vertical column). If the user needs to arrange widgets in this column in a custom order, the user can configure different order values for each widget.
-
Height - takes an integer value from 1 to 10. It sets the height of the widget in Mobile Mode in the range from 70px (1) to 700px (10), ignoring its original height. For example, with a value of 5, the widget height will be 350px. (70 * 5) If no value is specified, its original height will be used.
Mobile View
Import Widget
The user can import a widget from a JSON file.
To import a widget, follow these steps:
-
Open the dashboard and enter Edit Mode. Then click the "+ Add widget" icon at the top of the screen, or click the large "Add new widget" sign in the middle of the screen to open the Select widgets bundle dialog window
-
Click the "Import widget" button in the upper right corner of the screen
-
In the widget import window, upload the JSON file and click "Import"
-
The widget has been imported. However, the widget does not display data yet because the data source is not specified. Enter Edit widget mode to specify the data source
-
Specify the data source, add the data key(s), and apply changes
-
The data will get updated in the widget. After all the settings are made, save the dashboard
Export Widget
To export a widget, the user should go to a dashboard, where a widget is located.
Then go to the “Edit Mode”. Now in the upper right corner of the needed widget, click the button “Export widget”. This action saves the configuration file of the JSON format with all the settings of a particular widget.
