Overview

The following sections will walk you through all functionalities of the Cockpit application in detail.

For your convenience find an overview on the content of this document below.

Section Content
Managing assets Organize assets in hierarchies by creating groups and assigning devices.
Data explorer Interactively explore, compare and visualize IoT data.
Describes how to access and use the data explorer, add data points to the data explorer, customize data point properties, modify the visualization, store the data explorer as widget, and export the data.
Working with dashboards Create your own analytics and monitor pages by adding and arranging widgets. Share dashboards among all devices of the same type.
Working with reports Handle reports based on dashboard layouts.
Using widgets in dashboards and reports Create or arrange widgets to track and provide various information in dashboards and reports.
Widgets collection Use various types of widgets from the Widgets collection that comes with Cumulocity IoT and configure them according your needs.
Managing exports Configure exports for exporting data in CSV or excel format and schedule the export.
Data point library Manage default settings ("profiles") of your devices and apply them automatically using the data point library.
Smart rules Create and manage business rules to work on incoming data in realtime and to perform actions based on this data.
Smart rules collection Use pre-defined global smart rules to configure rules for geofencing, thresholds or alarm escalation and notifications (SMS/email). Describes each smart rule and its configurable parameters in detail.
Configuring Cockpit applications Configure custom Cockpit applications according to your individual needs.

If you want to learn more about general aspects of the Cumulocity IoT platform and its applications, refer to Getting Started.

Home dashboard

The Home screen of the Cockpit application is a dashboard which shows data for the general tenant.

Home dashboard

The data shown on the Home dashboard is shared by all users of the tenant. By default, the Home dashboard includes a welcome message, the active critical alarms, recent alarms and a map of all objects.

Info
For performance reasons, the map on the Home dashboard displays icons for a maximum of 100 devices. If there are more devices they are not be shown in the map. To see them, you must go to the dashboard on group level, and add the “Map” widget there to only see devices from this particular group, see Widgets collection.

The Home dashboard can be edited and designed individually according to your needs. You can add, remove or change widgets being displayed here.

For details on editing a dashboard, refer to Working with dashboards.

To reset the Home dashboard to its original content, click More… at the right of the top menu bar and then click Restore dashboard.

Managing assets

Assets hierarchy

Assets represent business objects in general like buildings, machines, production units or cars.

Assets are organized in hierarchies. For example, an energy monitoring application might have the following asset hierarchy:

image alt text

The asset hierarchy is composed of two types of objects:

In this example, the group objects represent a building asset. The device objects represent the room asset. The group names and hierarchy can be defined individually by the user. The hierarchy can have multiple levels, like region level, city level, street level, building level, floor level and room level. Any device can be part of multiple and different hierarchies, like part of regional hierarchy and part of customer hierarchy.

To position a device in the asset hierarchy, you must “assign” the device to the respective group (see below).

Info
Single devices are not managed in the Cockpit application. They are managed in the Device Management application.

Asset hierarchy versus device hierarchy

Cumulocity IoT supports two types of hierarchies: a device hierarchy and an asset hierarchy.

The device hierarchy tracks how devices are linked to Cumulocity IoT from a communications point of view. The asset hierarchy structures the assets that are being remotely supervised and controlled through the IoT devices. For details, refer to Cumulocity IoT’s domain model in the Concepts guide.

In the Cockpit application, you construct your asset hierarchy by creating group objects and by linking devices into the hierarchy. The asset hierarchy depends on the IoT devices used. There are many types of IoT devices, but these two types are very common:

The following section explains how to work with smart devices and gateway devices in the Cockpit application.

The first example shows how smart devices are linked into the asset hierarchy:

image alt text

Smart devices are represented as top-level devices in the Device Management application. In the Cockpit application, you can organize smart devices into groups, as the arrows indicate in the above diagram.

The second example shows how gateway devices can be used in the Cockpit application.

image alt text

Gateway devices are as well represented as top level devices in the Device Management application. Their attached devices (like for example Modbus or KNX devices) are shown as child devices. These child devices can be organized in the asset hierarchy in the Cockpit application as shown above.

As you can see from the example, devices can have completely different hierarchies in the Device Management application and in the Cockpit application: While inside Device Management all child devices are below the gateway device, the same child devices are organized in two different buildings in the Cockpit.

Cockpit assets versus business assets

The mapping of objects in the Cockpit asset hierarchy is a virtual hierarchy.

If you manage trucks within the Cumulocity IoT platform, then each truck is represented via its individual tracking device communicating with Cumulocity IoT.

For building management, it is most common that a group of sensors inside a building represents the building as a group communicating with the Cumulocity IoT platform.

How to navigate assets

In the asset hierarchy, Cumulocity IoT distinguishes between top-level groups and subassets. Subassets can either be other groups or devices.

In the navigator, top-level groups are shown in the Groups menu at top-level. Subassets are shown under its higher-level group.

Moreover, subassets are shown in the Subassets tab of the particular group which is initially displayed when you click on the group in the navigator.

Info
The count displayed on top of the table on the Subassets tab shows the total number of child assets assigned to the current group. Any type of managed object can be a child asset. For more details on the counting of objects refer to the operation Retrieve all child assets of a specific managed object in the Cumulocity IoT OpenAPI Specification.
Info
If you add a gateway device, the child devices are not shown. To show child devices, you must add them to the related asset. Details related to the child hierarchy are visible and editable in the Device Management application.

Use the navigator, to navigate through the asset hierarchy.

Asset details

Depending on the asset type (group or device), various tabs are available with detailed information.

Groups show the following tabs:

Requirements

ROLES & PERMISSIONS in groups context:

  • To view all groups: READ permission for permission type “Inventory”
  • To add new groups: CREATE permission for permission type “Inventory”
  • To delete any group: ADMIN permission for permission type “Inventory”
  • To rename a group or change group description: ADMIN permission for permission type “Inventory”
  • To view specific groups: READ permissions for “Inventory” in the inventory roles
  • To manage or delete specific groups: READ and CHANGE permissions for “Inventory” in the inventory roles

Note that global inventory permissions override inventory role permissions.

Devices show the following tabs:

Requirements

ROLES & PERMISSIONS in devices context:

  • To view all devices within a group: READ permission for permission type “Inventory”
  • To assign or unassign devices within a group: ADMIN permission for permission type “Inventory”
  • To delete any device within a group: ADMIN permission for permission type “Inventory”

If dashboards have been created for a group or device, they will also be added as a tab. See Working with dashboards for details.

Moreover, additional tabs may be displayed here in case the application has been extended with a custom Web SDK extension. Take a look at our Web SDK tutorials to see how to add a custom tab.

How to add a group

  1. Click Add group at the right of the top menu bar.
  2. In the resulting dialog box, enter a unique group name and an optional description and click Next.
  3. In the list, select the devices you want to add. You may apply filters to reduce the number of displayed devices.
  4. Click Create to create the new group.

The new group will be added to the groups list.

Info
A group can be created with “0” devices in it.

To add a new group as a child of an existing asset, navigate to its Subassets tab and click Add Group in the top menu bar.

How to assign devices to a group

Before adding a device to the asset hierarchy, it must be connected to Cumulocity IoT. Connecting devices to the platform is done in the Device Management application. For details on connecting devices refer to Device Management.

To assign devices to a group, follow these steps:

  1. In the navigator, select a group from the Group menu and then open the Subassets page.
  2. Click Assign devices at the right of the top menu bar.
  3. In the list, select the devices you want to add. You may apply filters to reduce the number of displayed devices.
  4. Click Assign to assign the selected devices.

The devices will be assigned to the selected group and shown as subassets in the Subassets page.

How to edit a group

  1. In the navigator, click a group to open it.
  2. In the Subassets tab, you can edit the name and description of the group.

How to delete a group

To delete a group either on top-level from the Groups page or from the Subassets tab of another group, hover over the respective entry you want to delete and click the delete icon at the right.

In the resulting dialog box, you can select to also delete all devices inside the selected asset and all its subassets.

How to remove a device from a group

  1. Navigate to the Subassets tab of the group.
  2. Hover over the respective device you want to remove and click the remove icon at the right.

Removing a device does not delete the device, subdevices or any associated data. The device is only removed from its location in the asset hierarchy. It can be assigned to this group or other groups later.

Data explorer

In the data explorer, data points (measurements or sensor data) can be visualized.

Requirements

ROLES & PERMISSIONS:

  • To view and select all available data points: READ permission for permission type “Inventory” or READ permission for “Inventory” in the inventory roles
  • To visualize already selected data points: READ permission for permission type “Measurements” or READ permission for “Measurements” in the inventory roles
  • To send as widget to report/dashboard: ADMIN permission for permission type “Inventory”

Note that datapoints existing in the data point library are visible by anyone without the need of any permission.

The data explorer is available for all assets at once or just for a particular asset.

In the data explorer, you see a list of available data points at the right. The first five data points of the selected device or group are shown by default. For details on how to add data points see To add a data point.

On the left, in the main card, you see its visualization.

Data explorer

The visualization is generated based on data point properties.

The data points properties are pre-filled as follows:

There can be more than one matching data point entry in the data point library. In this case, the first one is selected automatically by the system.

For details on modifying the visualization in general, see Changing data explorer visualization. For details on customizing the properties of a particular data point, see Customizing data point properties.

Example:

Let’s assume you have a temperature data point defined in the library and a device which sends temperature measurements (matching by fragment and series with the data point in the library). If you create an “On measurement threshold create alarm” smart rule and select the data point from the library, then it will use the settings from the library to decide whether to create an alarm.

Info
Data points are visible to all authenticated users of the tenant, regardless of their inventory role permission.

Changing data explorer visualization

To change the visualization in the data explorer, you can modify several properties.

Time range

You can change the time range being shown. By default, you see the values for the last hour.

To change the time range on the x-axis, use one of the following options:

Info
Real-time updates will be switched off if you set a time range in the past.

Aggregation

You may aggregate the data being displayed to get an efficient overview over larger time periods.

By default, aggregation is set to “None”. This value may be changed in the Aggregation field in the top menu bar. Available values are “Minutely”, “Hourly” or “Daily”, depending on the selected time range.

When aggregation is activated, the timestamp which is displayed in data point graphs or data point tables changes slightly as follows to improve transparency:

Realtime updating

By default, realtime updating is enabled which means that the data being shown is updated as new data flows into the system from the connected devices.

To turn realtime updating on or off, click Realtime in the top menu bar. A green light indicates, that realtime updating is enabled.

Data point visibility

For each data point, its visibility can be switched on or off by using the toggle left from the data point name.

To add a data point

To add a data point to the data explorer, click Add data point at the bottom of the Data points card.

Add data point

On the left hand side of the dialog, select a device from the asset hierarchy. Only the asset hierarchy below the objects selected in the navigator is visible. If Data explorer in the navigator was selected, the complete asset hierarchy is visible.

The center of the dialog shows all data points of the selected object. Select the data points you want to show in the data explorer. Click Add to add all selected data points to the list of data points.

The right hand side shows all of the selected data points.

For details on the data point library refer to Data point library.

To remove a data point from the data point list, click the menu icon and select Remove from list.

Customizing data point properties

You can customize the visualization of a particular data point to your preferences. To do so, expand the data point entry in the data point list.

The following fields may be modified:

Field Description
Label Name of the data point, displayed on the y-axis to identify the data point. Below the label, the target is displayed, showing the name of the asset and the internal name of the data point (measurement fragment and series). This information is not editable.
Unit Unit used on the y-axis.
Min/Max Range shown on the y-axis. If not specified, the y-axis is scaled based on measurement values retrieved per specified time range.
Target The target value is currently not shown in the diagram. The value is used in the "Data point list" widget.
Yellow range min/max Defines the range when MINOR alarms should be raised by threshold rule.
Red range min/max Defines the range when CRITICAL alarms should be raised by threshold rule.
Display Value displayed when data is aggregated. May be "Minimum", Maximum", Minimum and maximum".
Chart type The type of chart used for the visualization. May be one of "Line", "Points", "Line and points", "Bars", "Step before" (alternating between vertical and horizontal segments, as in a step function) or "Step after" (alternating between horizontal and vertical segments). Default value is "line".
Y axis Defines where the y-axis is shown. May be one of "Auto", "Left", "Right". Default value is "Auto".

Y-axis behaviour

Per default, the first data point is positioned to the left y-axis and the remaining data points to the right. This behavior can be changed by modifying the respective value “Y-axis” for a particular data point (to “Left” or “Right”, see above).

Each data point is shown on its own y-axis, unless the following condition is met:

In this case, both data points share the same y-axis. This y-axis only shows the unit (or multiple units, in case they are different). The label is not shown.

Adding alarms or events

In addition to data points you can also add alarms or events to the data explorer.

In the Alarms/Events card, click Add alarm/event to add an alarm or event.

In the upcoming dialog, you can select an alarm or event from the list of recent alarms and events. Click Add to add your selection.

Expand an event, to modify its properties.

Click the menu icon and in the context menu select Remove, to remove the entry from the list.

As with data points, you can turn the visibility of an alarm/ event in the data explorer on and off by using the toggle.

Creating widgets from the data explorer

If you want to keep your current configuration in the data explorer for later usage, save it as a widget.

Send as widget to dashboard

To create a widget from the data explorer of a particular asset, click More… in the top menu bar and select Send as widget to dashboard from the context menu.

In the upcoming dialog, select one of the dashboards available for the current object and click Select to add the data explorer as widget to the selected dashboard.

Info
To use this function, first a dashboard must be created. For details on dashboards, refer to Working with dashboards.

Send as widget to report

To create a widget from the data explorer of in the navigator, click More… in the top menu bar and select Send as a widget to report from the context menu.

In the upcoming dialog, select one of the reports available and click Select to add the data explorer as widget to the selected report.

Info
To use this function, first a report must be created. For details on reports, refer to Working with reports.

Exporting measurement data

You may download measurement data as CSV or Excel files. The exported data shows the following information, divided into columns:

To export measurement data, click the More… button in the top menu bar and select either Download as CSV or Download as Excel, according to your preferences.

The download will be generated, as shown in the upcoming dialog. This may take a while, depending on the number of data points added to the data explorer. Once the loading has been completed, click Download.

Working with dashboards

Cumulocity IoT allows you to create individualized dashboards for all your groups and devices. Dashboards provide you with a customized visualization of your data, for example, alarms and events, and allow you to trigger remote actions, by using a set of widgets. Widgets can display maps, images, graphs, tables, and other graphic representations of data.

Requirements

ROLES & PERMISSIONS:

  • To view dashboards: READ permission for permission type “Inventory” or READ permission for “Inventory” in inventory roles
  • To edit widgets within a dashboard: ADMIN permission for permission type “Inventory” or CHANGE permission for “Inventory” in inventory roles
  • To create a dashboard: CREATE or ADMIN permission for permission type “Inventory” or CHANGE permission for “Inventory” in inventory roles
  • To delete a dashboard: ADMIN permission for permission type “Inventory” or CHANGE permission for “Inventory” in inventory roles
  • To share/copy a dashboard: CREATE permission for permission type “Inventory” or CHANGE permission for “Inventory” in inventory roles

Cumulocity IoT comes with a number of preset widgets, see Widgets collection for details. You can also develop your own widgets and add them to your Cumulocity IoT account. Refer to the Web SDK guide for details.

To create a dashboard

To create your individualized dashboard, execute the following steps:

  1. In the Groups menu select the group or the device in the navigator for which to create a dashboard.

  2. Click the plus icon right from the tabs to open the dashboard editor.

  3. In the Tab section of the dashboard editor, provide the following information:

    • An icon which is shown next to the dashboard name in the navigator.
    • A menu label to be used as the name of the dashboard.
    • The location of the dashboard in the navigator, with “10000” being ordered first and “-10000” last.

  4. Enable the option Apply dashboard to all devices of type to share the dashboard with all devices of this type.

  5. In the Availability section, specify which users have access to the dashboard based on global roles. By default, all available global roles are selected, which means that a user with at least one such role has access to the dashboard.

    Info
    • Dashboard are always visible to its owner and to users with ADMIN permission for the permission type “Inventory”.
    • This functionality is entirely based on client-side solutions. If users have an accurate link to the dashboard, they will still be able to access it.
  6. In the Layout section you can select a theme for the dashboard (one of “Light”, “Dark”, “Transparent” or “Branded”) and a default header style for the widgets (one of “Regular”, “Border”, “Overlay”, or “Hidden”). Moreover, you can change the default widget margin (default value is 15 px).

  7. Enable the option Translate widget titles if possible, to have the widget title translated every time the language is changed.

    Info
    The widget titles will be translated only if a valid translation is available.
  8. In the Preview section at the right, a preview of the selected layout settings is immediately displayed to visualize your selections.

  9. Click Save to create and open the dashboard.


Next, widgets can be added to the report. They allow you to display more detailed data in your dashboard.

Refer to Using widgets in dashboards and reports for details on how to add, modify or remove widgets.

Sharing dashboards

You can create a dashboard for a specific device and share it with all devices of the same type. This is only possible though, if the type property is set for the device.

To do so, select the option Apply dashboard to all devices of type [TYPE] ([TYPE] is replaced with the type of the device that is currently selected).

A corresponding message will be displayed in the editor.

Changes made to this dashboard are automatically applied to all dashboard instances.

Info
You can only add widgets and data to the dashboard for the device itself. It is not possible to add data from child devices because the structure of these devices might be different from device to device.

To edit a dashboard

To edit a dashboard, click Edit in the top menu bar.

The dashboard editor will open up. For details on the fields, refer to To create a dashboard.

To copy a dashboard from one object to another

  1. Click More… in the top menu bar and from the context menu select Copy dashboard.

  2. Next, navigate to the object you want to copy the dashboard to and from the context menu select Paste dashboard [NAME] to insert the dashboard.

An alternative way to copy a dashboard is to use the “dashboard per type” approach. With the “dashboard per type” approach you share the dashboard from one object with all objects of the same type, see Sharing dashboards.

To delete a dashboard

To delete a dashboard from an object, click More… in the top menu bar and from the context menu select Delete dashboard.

Working with reports

Reports enable you to track applications, alarms, assets, and other data in a dashboard layout. Reports are global dashboard pages, regardless of the asset hierarchy.

Requirements

ROLES & PERMISSIONS:

  • To view reports: READ permission for permission type “Inventory”
  • To edit a report: ADMIN permission for permission type “Inventory”
  • To add a new report: CREATE permission for permission type “Inventory”
  • To delete a report: ADMIN permission for permission type “Inventory”

To show all reports, click Reports in the navigator.

In the Reports page you will find a list displaying all reports with their names, an optional description and a navigator toggle.

Reports

To open a report, click on its name in the report list. The report details will be displayed.

Use the toggle in the Show in navigator column, if you want to show the report more prominently on the first level in the navigator. If the toggle is turned on, the report will immediately appear in the navigator.

Report in navigator

See To create a report below for details on how to configure the position in the navigator.

To create a report

  1. Click Add report in the top menu bar to open the Add report dialog.
    Add report
  2. In the Menu label field, enter a name for the report and optionally provide a description below.
  3. Select Show in navigator if you want the report to be displayed in the navigator. Select the position of the report in the navigator. Depending on the value it will be positioned relative to the existing items. If for example “Home” has the value “10000” it will be positioned above “Home”, if the value is “10001” or higher.
  4. In the Layout section you can select a theme for the report (one of “Light”, “Dark”, “Transparent” or “Branded”) and a default header style for the widgets (one of “Regular”, “Border”, “Overlay”, or “Hidden”). Moreover, you can change the default widget margin (default value is 12 px). If you enable the option Translate widget titles if possible, the widget title will be translated every time the language is changed. Note that the widget titles will be translated only if a valid translation is available. Click Save to create the report and add it to the report list.
Info
In the Preview section at the right, a preview of the selected layout settings is immediately displayed to visualize your selections.

Next, widgets can be added to the report.

Refer to Using widgets in dashboards and reports for details on how to add, modify or remove widgets.

To edit a report

Click on a report name in the report list to open its details.

To edit the report, click Edit in the top menu bar.

The report editor will open up. For details on the fields, refer to To create a report.

To delete a report

  1. In the Reports page, hover over the report item you want to delete and click the delete icon showing up at the right.
  2. Confirm to delete the report.

Using widgets in dashboards and reports

Widgets can display maps, images, graphs, tables and other graphic representations of data. Widgets are useful to track information, for example on alarms, assets or applications, or provide maps, quick links and more in dashboards or reports.

Requirements

ROLES & PERMISSIONS:

  • To view widgets within dashboards: READ permission for permission type “Inventory” or READ permission for “Inventory” in the inventory roles
  • To edit a widget: ADMIN permission for permission type “Inventory” or CHANGE permission for “Inventory” in the inventory roles
  • To create a widget: ADMIN permission for permission type “Inventory” or CHANGE permission for “Inventory” in the inventory roles
  • To delete a widget: ADMIN permission for permission type “Inventory” or CHANGE permission for “Inventory” in the inventory roles

Some of the widget require additional permissions in order to visualize the data which they display. For example, the alarms widget requires READ permission for permission type “Alarms” in order to view all alarms.

Cumulocity IoT provides preset widget types, for details see the Widgets collection.

To add a widget to a dashboard or a report

  1. Click Add widget in the top menu bar or click the Add widget button on the main page (only available in case of an empty dashboard/report).

  2. In the Add widget dialog, select a widget type.

  3. Next, configure the widget. According to the selected widget type, different parameters may be specified under Configuration. For details on each widget type refer to Widgets collection.

  4. In the Appearence tab, you can customize the content and header style for the widget individually, in the same way as specifying the layout of a dashboard.

     
    Info
    The header styles "Regular" and "Border" can be used for all widgets while the header styles "Overlay" and "Hidden" remove the header and should only be used for widgets which benefit from a full-screen experience, for example "Image" or "Map". For other widgets, like "Alarms list" or "Data point table", these header styles should not be used.
    
  5. Click Save to add the widget to the dashboard or report.

Modifying widgets

Widgets may be rearranged on the dashboard/report. By dragging and dropping you can move the widget to another position.

By dragging the arrows on the bottom right corner of a widget, you can resize it.

To edit the properties of a widget, click the cogwheel icon at the top right corner of the widget and from the context menu select Edit.

To remove a widget from a dashboard or report, click the cogwheel icon at the top right corner of the widget and from the context menu select Remove.

Widgets can only be modified if the dashboard/report is unlocked. To lock/unlock it, use the toggle with the lock icon in the top menu bar.

Info
On touch devices like smartphones or tablets some functions may not be supported.

Selecting assets in widgets

The following section describes how to select one top-level asset, how to select child devices as asset and how to search or filter for assets in the widgets configuration.

To add an asset to a new or existing widget

On the Configuration tab of the widget editor, select the check boxes of the desired asset under Asset selection. Click Save to add the asset to the widget. You can select a single device or a whole group of devices, indicated by a folder icon. For details on selecting child devices, see To select child devices within groups as asset.

If you want to edit an asset of a widget, open the widget editor and click Clear. This clears the previous asset collection. Select the new desired asset and click Save.

For general instructions on how to add or modify widgets, see To add a widget to a dashboard or a report or Modifying widgets.

To select child devices as asset

If the asset is a group or a device with children, you see a folder icon next to their name as well as an arrow icon pointing right. Click the desired group or device with children in the list to open a new level displaying all assigned assets to that group or device. Select the desired asset. To return to the previous level, click on the arrow icon pointing left.

Select assets

If you want to select an unassigned device as an asset, you can find the unassigned devices in the Unassigned Devices folder, located on the first level of the selected group.

Info
You cannot select the Unassigned devices folder itself. However, each device inside this folder can be selected on the next level. Click Unassigned devices to open the next level with all unassigned devices. Click the desired device to select it.

To search and filter for assets

There are two methods which can be used to quickly find assets:

  1. Full text search, and
  2. filtering.

On the Configuration tab of the widget editor you can use the full text search field under Asset selection.

Through the full text search you can find assets in the whole hierarchy, but it requires exact matches, for example, the whole name of the asset.

After selecting the asset, you see all children of this asset. To return to the level above, click the “X” in the search field.

Info
The full text search is only available in the Home dashboard and the Report dashboards.

For details on the search functionality, see Getting Started > UI functionalities and features > Search and filter functionality.

Filtering

Filtering is another way to find assets. However, it only filters assets on the current level under Asset selection.

Filtering

For details on the filter functionality, see Getting Started > UI functionalities and features > Search and filter functionality.

Widgets collection

The Cockpit application includes preset widget types. Each widget type provides different parameters to configure and different data to be displayed.

The following types are available:

Widget Functionality
Alarm list Shows a list of alarms, filtered by objects, alarm severity and alarm status.
All critical alarms Displays all objects with a critical alarm.
Applications Provides a list of links to all available applications.
Asset notes Displays messages provided by the administrative user to all owners of the current widget.
Asset properties Provides a user-defined list of attributes of the current object.
Asset table Shows details of a selected asset and all its child devices in a table.
Data point graph Displays data points (measurements) in a graph.
Data point list Displays data points (measurements), one in each row, with current values and data point properties.
Data point table Lists data points (measurements) as a table.
Event list Allows to monitor events for a selected device.
Fieldbus device Lets you see the status of a modbus device and operate it.
Help and service Displays links to help and service resources.
HTML Shows user-defined content formatted in HTML.
Image Shows a single image to be selected from your file system by browsing.
Info Gauge Visualizes one data point in form of a radial gauge and multiple data points as labels.
Linear Gauge Displays data points in form of a linear gauge.
Map Shows the location of a device or all devices of a group.
Markdown Displays markdown content either from a URL or from a file.
Message sending Sends a message to a device.
Pie chart Displays data points (measurements) with current values in a pie chart presentation.
Radial Gauge Displays data points in form of a radial gauge.
Recent alarms Shows all alarms of all severities sorted by time.
Relay array control Allows to switch relays on or off independently in an array of relays.
Relay control Allows to switch a device relay on or off.
Rotation Allows to render an object model of a device.
SCADA Provides a graphic representation of the status of a device.
Silo Displays data points (measurements) with current values in a silo presentation.
Traffic light Shows the states of a device as traffic light.

Alarm list

The “Alarm list” widget shows a list of alarms, filtered by objects, alarm severity and alarm status. For details on the information provided for each alarm, refer to Device Management > Working with alarms.

Alarm list widget

Parameters to configure

Field Description
Title Widget title. By default, the widget type is used as title.
Target assets or devices Select groups or devices, optional HTML expressions which should be evaluated.
Status Only show devices with alarms of of the selected alarm status.
Type Only show alarms of the specified type(s). Details can be seen when clicking once on an alarm.
Severities Only show alarms of the selected alarm severity.
Order Alarms may be ordered by the active status (followed by severity and time, the default) or the severity (followed by time).

All critical alarms

The “All critical alarms” widget shows all objects with a critical alarm. Apart from the title, there are no additional parameters to be configured.

Critical alarms

For details on alarms, refer to Device Management > Working with alarms.

Applications

The “Applications” widget shows a list of links to all available applications. Apart from the title, there are no additional parameters to be configured.

Applications widget

For details on applications, refer to Administration > Managing applications.

Asset notes

The “Asset notes” widget displays messages provided by the administrative user to all owners of the current widget.

Asset notes widget

Only users with the permission to edit the home dashboard will be able to provide this message.

Asset properties

The “Asset properties” widget displays a user-defined list of attributes of the current object. The current object can be a device or a group.

Asset properties widget

Parameters to configure

Field Description
Title Widget title. By default, the widget type is used as title.
Target assets or devices Select groups or devices.
Properties List of properties, see Asset table.
Info
In the view mode, this widget only displays the properties which are not empty.

Asset table

The “Asset table” widget shows details of a selected asset and all its child devices in a table. This is a very powerful widget, allowing to arrange selected properties of objects in a table.

Parameters to configure

Field Description
Title Widget title. By default, the widget type is simply used as title.
Target assets or devices Select for which object all child devices should be shown. This is typically a group object.
Properties Select properties or actions of an object to visualize them as columns in the table.

Example

In the following screenshot, five columns are configured. Three property columns “Name”, “Owner”, and “Type”, which refer to the properties “name”, “owner” and “type” respectively. Additionally, there are two actions, one for toggling the maintenance mode, and one for rebooting the device.

Asset table widget

The resulting table is visualized as follows: Asset table widget example

To add properties

Click +Add Properties and select one or more properties to be added.

Info
The property “Active alarm status” shows active alarms as icons in the table. If you select this property, you also must configure the renderer “Active Alarm Status” in the list of columns.

To add actions

  1. Click +Add Action.
  2. Select Toggle maintenance mode to add the predefined action to toggle the maintenance mode.
  3. Select Create operation to create a button that will execute a shell command. In the resulting dialog box you can then enter the label for the button and the shell command to be executed.

Reboot device button configuration

Info
The dialog shows the predefined shell commands of the first device that supports shell commands. The list is empty if there is no such device. For more details, refer to Device Management > Device details > Shell.
You can also enter the JSON format for the operation that will be sent to the device. For details, contact the device vendor for supported operations.

To modify the table

To edit the header of a column, click on its value in the Label column and edit the label.

You can rearrange the columns by clicking the icon at the very left of a row and dragging and dropping the entry.

To remove a property or an action, hover over the respective row and click Delete at the right.

Data point graph

The “Data point graph” widget shows a data point (measurement) in a graph. The visualization is the same as in the data explorer.

Data Point Graph widget

The easiest way to create a “Data point graph” widget is to navigate to the data explorer, click the More… button in the top menu bar and select Send as widget to dashboard.

Refer to Visualizing data using the data explorer for further details on the parameters to be configured.

Data point list

The “Data point list” widget shows data points (measurements), one in each row, with current values and data point properties.

Parameters to configure

Field Description
Title Widget title. By default, the widget type is simply used as title.
Data point Shows a list of available data points. You must enable at least one data point. Click Add data point to add a data point to the list. For details on how to add data points see Data explorer > To add a data point.
Column visibility Select which columns should be visible:
Label: Label of the data point. See Visualizing data using the data explorer for details.
Target: Target value. Can be configured in the data explorer or data point library.
Current: Current value.
Diff: Absolute difference between current value and target value.
Diff %: Percentage of difference between current value and target value.
Asset: Name of the device or group of the data point.

Data point table

The “Data point table” widget configuration is similar to the “Data point graph” widget, but instead of visualizing the data as a line-chart, data is visualized as a table.

The “Data point table” widget displays data based on selected data points, time interval and aggregation.

Out of range values, based on configured yellow and red ranges, are highlighted in the table.

Data point table

At the top right of the data point list, an Auto scroll toggle determines the display behavior:

Auto-scroll toogle

Event list

The “Event list” widget lets you monitor events for a selected device.

Event list widget

Additionally, a specific date range can be set and the events can be monitored in realtime.

Fieldbus device

The “Fieldbus device” widget lets you see the status of a modbus device and operate it.

For details on the “Fieldbus device” widget, refer to Cloud Fieldbus > Monitoring the device status using the Fieldbus device widget in the Protocol integration guide.

Help and service

The “Help and service” widget displays links to help and service resources. There are no additional parameters to be configured.

Help and service widget

Image

The “Image” widget lets you display a single image to be selected from your file system by browsing. There are no additional parameters to be configured.

Info Gauge

The “Info gauge” widget visualizes one data point in form of a radial gauge and multiple data points as labels.

Info gauge widget

You can select one data point for the gauge, and multiple data points shown with labels at the left side.

You must enable at least one data point in each section to create the “Info gauge” widget.

HTML

The “HTML” widget shows user-defined content. The content can be formatted using HTML.

Parameters to configure

“Device” refers to the target device, as selected in the widget configuration parameter.
“fragment.property” refers to the properties of the respective device. To see the available property names, you can use the “Asset property” or “Asset table” widget and click +Add property in the widget configuration. This will show a table of supported properties. You can copy and paste the values from the column Property. Generated properties of these widgets are not available in the HTML widgets.

The following code sanitization options can be selected:

Info
The sanitization option “lax” includes a defined list of directives that are excluded from sanitization. For more examples on how to customize the sanitization options, see the help text toggle in the HTML code section.

HTML widget

If you want to use a link in the HTML code field, for example a link to a dashboard, you must use the following format:

  <a style="cursor:pointer;" onclick="location.hash = '#/group/<<group-id>>/dashboard/<<dashboard-id>>'">link to another dashboard</a><br />

Linear Gauge

The “Linear gauge” widget visualizes data points in form of a linear gauge. Min and max target values are shown on the gauge as well.

Info gauge widget

Info
If a label is not properly readable, you can help yourself by increasing the min and max value of the data point to move the label into the readable range.

You must enable at least one data point to create the “Linear gauge” widget.

Map

The “Map” widget shows the location of a device or all devices of a group.

Info gauge widget

You can drag the map and move its content, and you can zoom in and out by using the Plus and Minus buttons.

The icons representing the devices are color-coded. The color used follows these rules:

Click a device icon, to open a popup with the following information:

Parameters to configure

Target assets or devices: Select which devices are shown on the map. If a group is selected, all devices in that group (but not in any subgroups) are visible.

Info
If none of the target device(s) has a known location, then the widget shows a world map without icons.

Markdown

The “Markdown” widget can be used to display markdown content. Using the “Markdown” widget you can inform users, for example, on new features.

Markdown widget

There are several ways to provide markdown content:

Message sending

The “Message sending” widget sends a message to a device. The behavior of the device itself is device-dependent. Only available for devices that support the operation c8y_Message.

Pie chart

The “Pie chart” widget displays data points (measurements) with current values in a pie chart presentation.

Parameters to configure

Field Description
Title Widget title. By default, the widget type is simply used as title.
Pie chart options Select from the options to show tooltips, percentages, legends in the pie chart.
Data point Shows a list of available data points. You must enable at least one data point. Click Add data point to add a data point to the list. For details on how to add data points see Data explorer > To add a data point.

Radial Gauge

The “Radial gauge” widget visualizes data points in form of a radial gauge.

Radial gauge widget

You must enable at least one data point to create the “Radial gauge” widget.

Recent alarms

The “Recent alarms” widget shows all alarms of all severity sorted by time. There are no additional parameters to be configured.

Recent alarms widget

For details on alarms, refer to Device Management > Working with alarms.

Relay array control

The “Relay array control” widget lets you switch relays on or off independently in an array of relays. Only available for devices that support this type of operation.

Relay control

The “Relay control” widget allows you to switch a device relay on or off. Only available for devices that support this type of operation.

Rotation

The “Rotation” widget lets you render an object model of a device.

Parameters to configure

Field Description
Title Widget title. By default, the widget type is simply used as title.
Target assets or devices Select group or device to be displayed.
Object model for rendering Select an object model type for rendering. May be one of “Box model” or “Phone model”.
Wireframe Turn “Wireframe” on or off (default = on). The “wireframe” mode displays the object in a skeletal representation.
Camera type Select the type of camera to be used. May be one of “Orthographic camera” or “Perspective camera”.

In the “Rotation” widget you can rotate the object by dragging and moving it around. Zoom in and out by using the mouse.

SCADA

The “SCADA” widget provides a graphic representation of the status of a device.

For details on the “SCADA” widget, refer to Cloud Fieldbus > Monitoring the device status using the SCADA widget in the Protocol integration guide.

The following code sanitization options can be selected:

SCADA widget

Silo

The “Silo” widget displays data points (measurements) with current values in a silo presentation.

Parameters to configure

Field Description
Title Widget title. By default, the widget type is simply used as title.
Data point Shows a list of available data points. You must enable at least one data point. Click Add data point to add a data point to the list. For details on how to add data points see Data explorer > To add a data point.

Traffic light

The “Traffic light” widget visualizes the states of a device as traffic light.

Parameters to configure

Field Description
Title Widget title. By default, the widget type is simply used as title.
Target assets or devices Select group or device to be displayed.
States mapping Select a property for each light. The value of the property must be one of the following to have the respective light on: true, 1, any non-empty string, any non-null number.

Managing exports

The export functionality lets you export specific data to either CSV or Excel files.

Requirements

ROLES & PERMISSIONS:

  • To view exports: READ permission for permission type “Inventory”
  • To edit an export: ADMIN permission for permission type “Inventory”
  • To add a new export: CREATE or ADMIN permission for permission type “Inventory”
  • To schedule an export: ADMIN permission for permission type “Schedule export”
  • To duplicate an export: ADMIN permission for permission type “Inventory”
  • To delete an export: ADMIN permission for permission type “Inventory”

With this feature, you can request data for the whole tenant. Additionally, you can choose to filter for specific devices, time ranges or fields. The export data contains information about all specified filters and enabled fields.

To show all exports, click Export in the Configuration menu in the navigator.

In the Export page you will find a list displaying all exports with their names, file type and time range.

Exports

To add an export

  1. Click Add export in the top menu bar.

  2. Enter a name for the export and select the file type (CSV or XLSX) for the report output.

Filters

In the Filter section, you can select filters to request object- or time-specific data.

To filter for a particular object, enter a name or property value into the search field and click the search icon. All matching devices or groups will be displayed below the Value field. Click an object to select it (highlighted in green).

Info
If you select a group, the data of direct child devices will be included. However the export will not contain the data of devices in subgroups (indirect children).

The Time range filter can filter data for a specific time range. Select a time range from the dropdown field. This may be one of “Last year”, “Last month”, “Last week”, or you may select “Custom” and enter a custom from/to range in the additional fields.

Select the Object to export and Time range checkboxes to enable the respective filters.

Info
The maximum number of documents matching the defined filters that can be returned is 1 million. If the number of documents for the defined filters exceeds this limit, only the first 1 million documents will be exported. Additionally, when the result is truncated due to this limitation, an additional line with an indicator is added at the end of the file. The indicator row contains the statements “limit exceeded!” and “result truncated!” alternating every other column.

Fields

Apart from object- and time-specific filtering you may filter data for specific fields:

Use the toggle to enable/disable a field.

Info
The time range filter only applies to alarms, events and measurements but not to managed objects. If selected, managed objects will appear in the export, regardless of any specified time range.

When a field is enabled, predefined or empty properties can be added.

Info
Documents that have no value defined for any of the selected fields are removed from the resulting export file. This is done only after the result of filters defined above was already calculated. This is commonly the reason why resulting files rarely reach the hard limit of 1 million rows.
To add a property

Click Add to add empty properties. To enter a label or path, click Column or Path and edit the field. For example, if you enable the Alarms field you could enter “Severity” in column and path to receive data for alarm severities.

Click Add predefined, to add predefined properties. Simply select the desired properties from the list and click Select. Use the search field at the top to search for a specific property.

If you have at least one field that is not originating from the “Add predefined” list but defined as a custom property, then you must set up at least one property for the custom values to appear in the export.

Example: An export has 4 fields defined: time range, device name, type and c8y_SpeedMeasurement.speed.value. The first 3 are predefined properties, while the last one is a custom property. If any measurement for export does not have a custom property c8y_SpeedMeasurement.speed.value, then it will not appear in the export file.

If your field is a valid.key.with.dot then refer to it as [‘fragment.key.with.dot’] in the path, for example: [‘fragment.key.with.dot’].series.value

In case of measurements enabled, you can also choose Add from data point. For details on how to add data points see To add a data point.

JsonPath expressions added from data points will be stored in bracket notation in order to increase the flexibility in fragment and series naming (for example whitespaces will be supported):

Measurement added from data point

To schedule an export

To schedule an export to a CSV or XLSX file to any point in time, open the respective export and click Add schedule at the bottom.

In the resulting dialog box provide the following information to receive the scheduled export via email.

Schedule export

1 - Frequency

Select the frequency for sending the export from the dropdown list, that is, every hour, day, week, month or year. Depending on the frequency selected, provide additional timing information. For example, if you have selected “every month”, provide the day of month, hour and minute.

Info
Schedule intervals must be provided in Coordinated Universal Time (UTC).

2 - Send email:

Complete the email information.

In the Send to field, provide the email address of the recipient. This field is mandatory. Optionally, you can provide email addresses for recipients of copies (CC) or blind copies (BCC). Use comma as separator to enter multiple recipients.

Optionally, add the email address of the sender for reply.

Specify the subject of the email. This field is pre-filled, but may be modified.

Enter the actual email message. Available placeholders are {host}, {binaryId}. The default value is “File with exported data can be downloaded from {host}/inventory/binaries/{binaryId}”. Note that to create a clickable link in the email, you must add “https://” to the link. For example: “A file with exported data can be downloaded from https://{tenant-domain}/inventory/binaries/{binaryId}.”

Info
Note that the corresponding emails are sent with “text/html” as the Content-Type header.

Click Create to create the new export schedule.

The export schedule will be added to the export details.

Migration of scheduled exports

With version 10.6.2, a new report agent has been implemented to allow scheduled exports. The export schedules functionality based on smart rules has been deprecated.

On opening a report, all scheduled exports based on smart rules are automatically migrated to the new report agent, while displaying a message informing the user about the process.

Important
You must open each report manually, to migrate the export schedules included in the report.
Info
To use the new export schedule feature and for the migration to work, the report-agent microservice needs to be subscribed. New tenants will be subscribed to it automatically. Existing tenants should make sure that they are subscribed to it.

To export data

To export data to a CSV or XLSX file, select the checkbox in front of the respective row in the list and at the left of the top menu bar click Export.

You will receive an email containing links to each export file.

Standard time properties (like time or creationTime in alarms) are exported to the XLSX and CSV files following the date and time format representation defined in ISO-8601.

When the export documents limit is reached and the result is truncated due to its limitations, an additional line with an indicator is added at the end of document.

Sample CSV export with indicator:

Time,Device name,Creation time,Device name,ID,Source,Text,Time,Type 2021-11-25T10:37:06.485Z,Position #1,2021-11-25T10:37:06.485Z,Position #1,1266,1195,Location updated,2021-11-25T10:37:06.485Z,c8y_LocationUpdate 2021-11-25T10:37:01.484Z,Position #1,2021-11-25T10:37:01.484Z,Position #1,1265,1195,Location updated,2021-11-25T10:37:01.484Z,c8y_LocationUpdate […] limit exceeded!,result truncated!,limit exceeded!,result truncated!,limit exceeded!,result truncated!,limit exceeded!,result truncated!,limit exceeded!

To edit an export

Just click the respective row or click the menu icon at the end of the row and then click Edit.

For details on the fields see To add an export.

To duplicate an export

  1. Click the menu icon at the end of the row and then click Duplicate.
  2. Modify at least the name.
  3. Click Save & close to save the export and return to the export list.

To delete an export

Click the menu icon at the end of the row and then click Delete.

Data point library

The data point library provides a collection of data points with default values for data point properties.

Requirements

ROLES & PERMISSIONS:

  • To add a data point: CREATE or ADMIN permission for permission type “Inventory”
  • To delete a data point: ADMIN permission for permission type “Inventory”
  • To edit a data point: ADMIN permission for permission type “Inventory”

Data point properties are similar to paragraph formats in word processing applications. You do not want to format each paragraph individually. Instead you want to define a set of default formats and apply them to your paragraphs in your document. The data point library provides the same functionality for data points. It provides a number of default data point templates that can be easily applied to your data points from different devices.

How does the Cockpit application use the data point library? To find the default visualization for a data point like color or label, the Cumulocity IoT platform searches the data point library and tries to find a matching entry. An entry is considered as “matching”, if the values for fragment and series in the data point library match those of the measurement. If there is a match, the corresponding data point properties are used for a default visualization.

Additionally, the properties of the data point library are used by threshold business rules: The red and yellow values configured in the data point library are used by the threshold rules to raise alarms.

To open the data point library, click Data point library in the Configuration menu of the navigator.

Data point library

A list of available data points will be opened. For each data point, the following information is provided in the list:

To add a data point to the library

  1. Click Add data point in the top menu bar.
  2. Provide the following information:
Field Description
Color Color for the data point visualization
Label Label to identify the data point
Fragment Name of the fragment
Series Name of the series
Unit Unit used for the measurement
Target Target value
Minimum Minimum value shown on the y-axis
Maximum Minimum value shown on the y-axis
Yellow range Min/max values for the yellow range (MINOR alarms)
Red range Min/max values for the red range (CRITICAL alarms)
Info
With the button next to the fragment and series fields you can pick the values for fragment and series from an existing data point using the data point selector.
  1. Click Save to add the data point to the library.

To edit a data point

Simply click the respective entry in the list or click the menu icon at the right of an entry and then click Edit.

To delete a data point

Click the menu icon at the right of an entry and then click Delete.

Smart rules

Cumulocity IoT includes the Streaming Analytics application which can analyze data in realtime and perform actions based on data.

To easily create rules, the Cockpit application includes a smart rules builder which allows you to create rules from templates (so-called smart rule templates).

Requirements
The smart rules functionality is only available if the tenant is subscribed to the Smartrule microservice and the Apama-ctrl microservice.

Smart rules are parameterized. There are two sources for parameters:

There are two different types of smart rules:

Requirements

ROLES & PERMISSIONS for global smart rules:

  • To view a global smart rules: READ permission for permission type “Global smart rules” or “CEP management” and READ permission for permission type “Inventory”
  • To edit global smart rules: ADMIN permission for permission type “Global smart rules” or “CEP management” and ADMIN permission for permission type “Inventory”
  • To create a global smart rule: ADMIN permission for permission type “Global smart rules” or “CEP management” and CREATE or ADMIN permission for permission type “Inventory”
  • To duplicate a global smart rule: ADMIN permission for permission type “Global smart rules” or “CEP management” and CREATE or ADMIN permission for permission type “Inventory”
  • To delete a global smart rule: ADMIN permission for permission type “Global smart rules” or “CEP management” and ADMIN permission for permission type “Inventory”
Requirements

ROLES & PERMISSIONS for local smart rules:

  • To view local smart rules: READ permission for permission type “Inventory” or READ permission for “Inventory” in the inventory roles
  • To edit local smart rules: ADMIN permission for permission type “Inventory” or CHANGE permission for “Inventory” in the inventory roles
  • To create a new local smart rule: CREATE permission for permission type “Inventory” or CHANGE permission for “Inventory” in the inventory roles
  • To delete a local smart rule: ADMIN permission for permission type “Inventory” or CHANGE permission for “Inventory” in the inventory roles

Smart rules can be seen in two places:

To create a smart rule

Smart rules can both be created in the Global smart rules page (global smart rules), accessible from the Configuration menu in the navigator, or in the Info tab of any group or a device (local smart rules).

  1. Click Add smart rule in the top menu bar.
  2. Select a smart rule template from the list. Note that this list might differ based on your installation.
  3. In the resulting dialog box, use the toggle to select if the rule will be enabled or disabled, see To enable/disable a smart rule for details.
  4. Next, configure the rule parameters. The parameters differ from rule to rule, for details see the individual rule descriptions in Smart rules collection.
  5. Click Create to create the smart rule.
Info
When you create a smart rule in the Global smart rules page, it will be active for all assets by default, unless you select target asset(s) in step 4 of the dialog box, see also To enable/disable a smart rule.

Smart rules can be instantiated multiple times.

To edit a smart rule

Click the menu icon at the right of an entry and then click Edit.

For details on the fields see To create a smart rule.

To duplicate a smart rule

  1. Click the menu icon at the right of an entry and then click Duplicate.
  2. Modify at least the name.
  3. Click Save & close to save the smart rule and return to the smart rule list.

To delete a smart rule

Click the menu icon at the right of an entry and then click Delete.

To debug a smart rule

Info
This feature is not available with Apama.

For easier debugging, there is a direct link from a smart rule to the corresponding event processing module.

Click the menu icon at the right of an entry and then click Inspect to use this link.

To enable/disable a smart rule

If a smart rule is set to Enabled in the edit dialog (accessible from the Global smart rules page and the Info tab of a particular device/group), it is globally “turned on” (that means, its underlying module gets deployed) so that the rule is available for devices and groups.

If it is set to Disabled it is “turned off” (that means, its underlying module is not deployed).

In addition to globally enabling/disabling a smart rule, a smart rule can be in active or inactive state for particular objects (groups or devices). If active, the rule will process events for these groups and devices.

Info
On creating a smart rule in the Global smart rules page, it will be active by default for all assets, unless you explicitly select target asset(s). If specific target assets are selected, it will be deactivated for all other assets. A local smart rule created in the Info page of a particular group or device is automatically activated for the respective target asset (and its direct children).

To explicitly activate or deactivate a rule, navigate to the Info tab of the particular group or device and set the Active/Inactive toggle to Active or Inactive respectively.

An example use case for deactivating a smart rule for a single object could be that a particular device is generating too many threshold alarms. The rule can be deactivated for this device only, but still be active for all other objects.

In case of a group, you activate/deactivate the smart rule with the toggle for the group alone. You can then separately activate/deactivate the rule for the group’s children via the dropdown box below the toggle.

Important
A rule which is activated for a particular object only works if the rule is also globally enabled.

Example: Defining explicit thresholds

To define a threshold rule follow these steps:

  1. In the navigator, select the desired group or device to apply a threshold to.
  2. Switch to the Data explorer tab.
  3. If the data point that should raise the threshold is not visible by default, select Add data point and add a data point.
  4. Click the menu icon at the end of the row of the respective data point and select Create smart rule.
  5. Select the smart rule “On measurement explicit threshold create alarm”.
  6. Fill in the red range minimum and red range maximum value. When the measurement value enters or leaves the RED range, an alarm is created or respectively cleared. For details, see the description of the rule “On measurement explicit threshold create alarm” in the Smart rules collection.
  7. Under Create Alarm you can optionally edit the alarm type and the alarm text.
  8. Under Target assets or devices you can select the object this rule will be applied to.
  9. Click Create to create the smart rule.

The rule will automatically be set to active and alarms appear if they arise.

Chain rule execution

Smart rules can create a new data item on the platform. For example, the threshold rule creates new alarms. This new data can be handled further by selected smart rules, for example, by an “On alarm send e-mail” rule.

Using this mechanism, it is possible to create a chain of smart rules.

Info
If you create a rule chain keep in mind how much data will be created and avoid overload or excessive amount of data.

Smart rules collection

Cumulocity IoT includes preset global smart rule types. Each global smart rule type provides different parameters to configure.

The following types are available:

Smart rule Functionality
On alarm send SMS If an alarm is created, an SMS is sent.
On alarm send email If an alarm is created, an email is sent.
On alarm escalate it If an alarm is created, an email or SMS is sent.
On alarm duration increase severity If an alarm is active for a certain time, the severity is increased.
On geofence create alarm If a geofence border is crossed, an alarm is created.
On geofence send email If a geofence border is crossed, an email is sent.
Calculate energy consumption Creates consumption data points based on data from an electric, gas, or water meter.
On missing measurements create alarm If no new measurement data has been received for a specified time, an alarm is created.
On alarm execute operation If a certain alarm occurs, the specified operation will be sent to the device.
On measurement explicit threshold create alarm If the measurement value enters or leaves the red range, a CRITICAL alarm is generated or cleared. This rule is similar to the rule "On measurement threshold create alarm". However, it provides the red threshold value explicitly.
On measurement threshold create alarm If the measurement value enters or leaves the red/yellow range, an alarm is created or respectively cleared. This rule extracts the thresholds values from the device or data point library.
Info
In certain rule parameters, various trigger fields can be used as variables, see Smart rule variables at the end of this section.

On alarm send SMS

Functionality

If an alarm is created, an SMS is sent.

Requirements
This rule is only available if your tenant has a configured SMS provider.

Parameters

The rule uses the following parameters:

Step Field Description
1 Rule name Pre-filled with the name of the rule template. Can be modified according to your needs.
2 On alarm matching The types of alarms triggering the rule. For each newly created alarm with one of these types in the list the rule is triggered.
3 Send SMS Phone number: Target phone number. It is recommended to include mobile country code for all numbers, for example, "+49" or "0049" for Germany. Multiple numbers can be separated by a comma (",", do not use a space!).
Message: Text of SMS with max. 160 characters. You can use variables of the form #{name}, see Smart rule variables.
4 Target asset or devices Select a group or device the rule shall be applied to. To activate the smart rule in other assets or devices, navigate to the respective objects and enable the smart rule. The smart rules details will show a list "Active for target asset or devices".
If you leave this field empty, the smart rule will be applied to every group and device. You can then deactivate the smart rule for specific assets or devices. In this case the smart rules details will show a list "Inactive for target asset or devices".
For details on enabling/disabling a smart rule, see To enable/disable a smart rule for a group or device.

You can select a single group or a single device (just one, not multiple). To enable it in other assets or devices you must navigate to each context and enable it there. Afterwards you’re able to see all target assets or devices in a list with the title “Active for target asset or devices” in the smart rule detail

Troubleshooting

Important
There is a limit of 160 characters as a total count. If you use variables and after applying the variables the text counts more than 160 characters the SMS will not be sent.

On alarm send email

Functionality

If an alarm is created, an email is sent.

Info
Note that the corresponding emails are send with “text/html” as content type.

Parameters

The rule uses the following parameters:

Step Field Description
1 Rule name Pre-filled with the name of the rule template. Can be modified according to your needs.
2 On alarm matching The types of alarms triggering the rule. For each newly created alarm with one of these types in the list the rule is triggered.
3 Send email Send to:/Send CC to:/Send BCC to: Email addresses for sending the email to. Multiple addresses can be separated by a comma (",", do not use a space!).
Reply to: Address to be used to reply to the message.
Subject: Subject of email. You can use a variable of the form #{name}, see Smart rule variables.
Message: Text of the email. You can use a variable of the form #{name}, see Smart rule variables.
4 Target asset or devices Select a group or device the rule shall be applied to. To activate the smart rule in other assets or devices, navigate to the respective objects and enable the smart rule. The smart rules details will show a list "Active for target asset or devices".
If you leave this field empty, the smart rule will be applied to every group and device. You can then deactivate the smart rule for specific assets or devices. In this case the smart rules details will show a list "Inactive for target asset or devices".
For details on enabling/disabling a smart rule, see To enable/disable a smart rule for a group or device.

On alarm escalate it

Functionality

If an alarm is created, sends email or SMS.

Requirements
This rule is only available if your tenant has a configured SMS provider.

Parameters

The rule uses the following parameters:

Step Field Description
1 Rule name Pre-filled with the name of the rule template. Can be modified according to your needs.
2 On alarm matching The types of alarms triggering the rule. For each newly created alarm with one of these types in the list the rule is triggered.
3 Escalate as follows Escalation steps processed in a chain.
Click Add step to define at least one step:
Type: Type of action executed in the step. Possible values are:
- Email (see "On alarm send email" rule for parameter descriptions).
- SMS (see "On alarm send SMS" rule for parameter descriptions).
Condition: The condition applied when the rule will be executed. Possible values are:
- Always: Action will always be executed.
- Always: If step N failed. Only phone steps may fail. The step is marked as failed once all retries have been made without a successful call. This option only appears if there already is a phone step configured that can be referred to.
4 Target asset or devices Select a group or device the rule shall be applied to. To activate the smart rule in other assets or devices, navigate to the respective objects and enable the smart rule. The smart rules details will show a list "Active for target asset or devices".
If you leave this field empty, the smart rule will be applied to every group and device. You can then deactivate the smart rule for specific assets or devices. In this case the smart rules details will show a list "Inactive for target asset or devices".
For details on enabling/disabling a smart rule, see To enable/disable a smart rule for a group or device.

Troubleshooting

On alarm duration increase severity

Functionality

If an alarm is active for a certain time, the severity is increased.

Parameters

The rule uses the following parameters:

Step Field Description
1 Rule name Pre-filled with the name of the rule template. Can be modified according to your needs.
2 On alarm matching The types of alarms triggering the rule. For each newly created alarm with one of these types in the list the rule is triggered.
3 Increase alarm severity Duration, an alarm must be active, before increasing the severity.
4 Target asset or devices Select a group or device the rule shall be applied to. To activate the smart rule in other assets or devices, navigate to the respective objects and enable the smart rule. The smart rules details will show a list "Active for target asset or devices".
If you leave this field empty, the smart rule will be applied to every group and device. You can then deactivate the smart rule for specific assets or devices. In this case the smart rules details will show a list "Inactive for target asset or devices".
For details on enabling/disabling a smart rule, see To enable/disable a smart rule for a group or device.

Description

When a configured type of alarm is raised, it starts monitoring how long the alarm stays active.

If the alarm is still active after the specified duration, the severity will be increased one level, for example, from MINOR to MAJOR.

If the alarm has reached CRITICAL, it will stop monitoring because there is no further action possible.

Info
The rule checks once a minute if the configured duration has been exceeded. Therefore it might happen that the alarm severity won’t change in the second it exceeds the duration but only after the following check.

On geofence create alarm

Functionality

If a geofence border is crossed, an alarm is created.

The rule can be configured for entering or leaving the geofence, or both. Existing alarms are cleared when the opposite condition is true again, for example, if a tracked car which has left the geofence area is re-entering the geofence area.

Parameters

The rule uses the following parameters:

|

Step Field Description
1 Rule name Pre-filled with the name of the rule template. Can be modified according to your needs.
2 On geofence violation Polygon that defines the borders of an area. Click Edit geofence and set the area. Double-click to add points and click and drag them to adjust.
3 Create alarm Trigger: Reason for triggering the alarm: "On entering", "On leaving" (the default), "On entering and leaving".
Type: Type of alarm being raised. It is strongly recommended to use different types of alarms for each smart rule. If the same alarm type is used across multiple smart rules, smart rules may interfere when trying to update the same alarm type, which might lead to unexpected behavior.
Severity: Severity of alarm being raised.
Text: Alarm message.
4 Target asset or devices Select a group or device the rule shall be applied to. To activate the smart rule in other assets or devices, navigate to the respective objects and enable the smart rule. The smart rules details will show a list "Active for target asset or devices".
If you leave this field empty, the smart rule will be applied to every group and device. You can then deactivate the smart rule for specific assets or devices. In this case the smart rules details will show a list "Inactive for target asset or devices".
For details on enabling/disabling a smart rule, see To enable/disable a smart rule for a group or device.
Info
In order to raise an alarm the device had to be inside the geofence at least once after creating the rule.

Troubleshooting

On geofence send email

Functionality

If a geofence border is crossed by leaving the geofence area, an email is sent.

Info
Note that the corresponding emails are send with “text/html” as content type.

Parameters

The rule uses the following parameters:

Step Field Description
1 Rule name Pre-filled with the name of the rule template. Can be modified according to your needs.
2 On geofence violation Polygon that defines the borders of an area. Click Edit geofence and set the area. Double-click to add points and click and drag them to adjust.
3 Send email Send to:/Send CC to:/Send BCC to: Email addresses for sending the email to. Multiple addresses can be separated by a comma (",", do not use a space!).
Reply to: Address to be used to reply to the message.
Subject: Subject of email. You can use a variable of the form #{name}, see Smart rule variables.
Message: Text of the email. You can use a variable of the form #{name}, see Smart rule variables.
4 Target asset or devices Select a group or device the rule shall be applied to. To activate the smart rule in other assets or devices, navigate to the respective objects and enable the smart rule. The smart rules details will show a list "Active for target asset or devices".
If you leave this field empty, the smart rule will be applied to every group and device. You can then deactivate the smart rule for specific assets or devices. In this case the smart rules details will show a list "Inactive for target asset or devices".
For details on enabling/disabling a smart rule, see To enable/disable a smart rule for a group or device.
Info
In order to perform the rule the device had to be inside the geofence at least once after creating the rule. An email is triggered on leaving the geofence area.

Troubleshooting

Calculate energy consumption

Functionality

Creates consumption data point based on data from an electric, gas, or water meter.

Parameters

The rule uses the following parameters:

Step Field Description
1 Rule name Pre-filled with the name of the rule template. Can be modified according to your needs.
2 Monitored measurement Fragment/Series: Name of the measurement fragment and series. The incoming measurement must have exactly the same fragment/series name as configured. When creating a rule from the data explorer, these fields are already filled in.
Time interval: Interval in which consumption values shall be calculated. Specifies how often per hour the consumption is calculated.
3 Energy consumption measurement Name of the measurement fragment and series that shall be generated.
4 Target asset or devices Select a group or device the rule shall be applied to. To activate the smart rule in other assets or devices, navigate to the respective objects and enable the smart rule. The smart rules details will show a list "Active for target asset or devices".
If you leave this field empty, the smart rule will be applied to every group and device. You can then deactivate the smart rule for specific assets or devices. In this case the smart rules details will show a list "Inactive for target asset or devices".
For details on enabling/disabling a smart rule, see To enable/disable a smart rule for a group or device.

The unit of the consumption measurement is always per hour (that means, if the measurements are in “kg” the consumption will be in “kg/h”).

The rule takes the last two measurements for a specified time, calculates the difference in value and time and then calculates the consumption per hour.

Example

The rule is configured to calculate every 20 minutes. The following measurements are coming in: 100 kg at 11:59 and 200 kg at 12:14. At 12:20 the rule is triggered, taking the last two measurements. It calculates value and time difference. The consumption measurement created at 12:20 will therefore be 400 kg/h. If no new measurement was created in the last period a measurement with consumption 0 will be created.

On missing measurements create alarm

Functionality

If no new measurement data has been received for a specified time, an alarm is created.

Parameters

The rule uses the following parameters:

Step Field Description
1 Rule name Pre-filled with the name of the rule template. Can be modified according to your needs.
2 Monitored measurement Type: Type of measurement. The incoming measurement must have the same type as configured. When creating a rule from the data explorer, the type is already filled in.
Time interval: Interval for calculating consumption values.
3 Create alarm Type: Type of alarm being raised. It is strongly recommended to use different types of alarms for each smart rule. If the same alarm type is used across multiple smart rules, smart rules may interfere when trying to update the same alarm type, which might lead to unexpected behavior.
Severity: Severity of alarm being raised.
Text: Alarm message.
4 Target asset or devices Select a group or device the rule shall be applied to. To activate the smart rule in other assets or devices, navigate to the respective objects and enable the smart rule. The smart rules details will show a list "Active for target asset or devices".
If you leave this field empty, the smart rule will be applied to every group and device. You can then deactivate the smart rule for specific assets or devices. In this case the smart rules details will show a list "Inactive for target asset or devices".
For details on enabling/disabling a smart rule, see To enable/disable a smart rule for a group or device.
Info
The rule checks once a minute if the configured time interval was exceeded. Therefore it can take up to one minute to create the alarm after the time interval was exceeded. To check if the time interval was exceeded there must be at least one incoming measurement after the activation of the rule.

On alarm execute operation

Functionality

If a certain alarm occurs, the specified operation will be send to the device.

Parameters

The rule uses the following parameters:

Step Field Description
1 Rule name Pre-filled with the name of the rule template. Can be modified according to your needs.
2 On alarm matching The types of alarms triggering the rule. For each newly created alarm with one of these types in the list the rule is triggered.
3 Execute operation The operation that will be sent. The operation is provided as JSON description. Some standard operations can be selected below the Operation field. To use a standard operation, select one, and press the arrow button at the right. This will insert the JSON of the selected operation.
4 Target asset or devices Select a group or device the rule shall be applied to. To activate the smart rule in other assets or devices, navigate to the respective objects and enable the smart rule. The smart rules details will show a list "Active for target asset or devices".
If you leave this field empty, the smart rule will be applied to every group and device. You can then deactivate the smart rule for specific assets or devices. In this case the smart rules details will show a list "Inactive for target asset or devices".
For details on enabling/disabling a smart rule, see To enable/disable a smart rule for a group or device.

On measurement threshold create alarm

Functionality

If the measurement value enters or leaves the red/yellow range, an alarm is created or respectively cleared.

The severity of alarm is determined as follows:

The rule uses the following parameters from the device object or data point library:

Examples

Example 1 - Red range:

If we set the red range to “[60;90]”

and the measured value is between 60 - 90 (including the values 60 and 90) as a result a CRITICAL alarm (red) will be created.

Example 2 - Yellow range:

If we set the yellow range to “[30;50)”

and the measured value is between 30 - 49 as a result a MINOR alarm (yellow) will be created. The value 50 is out of the yellow range.

Example 3 - Red and yellow range:

As a result of the above behavior, we can set configurations like the following:

If the measured value is 60, then as a result a CRITICAL alarm (red) will be created because red includes the value 60.

Example 4 - Overlap:

The red range and the yellow range can overlap. A value in this overlap range is treated as being in the yellow range.

If we set the yellow range to “[30;60)” and the red range to “[50;90]":

and the measured value is 55, a MINOR alarm (yellow) will be created.

Using these mechanisms, you can configure global threshold ranges in the data point library. These global values can then be overridden for specific objects on a case-by-case basis.

Parameters

The rule uses the following parameters:

Step Field Description
1 Rule name Pre-filled with the name of the rule template. Can be modified according to your needs.
2 On threshold Fragment/Series: Name of the measurement fragment and series. The incoming measurement must have exactly the same fragment name as configured. When creating a rule from the data explorer, these fields are already filled in.
Data point library entry: Name of the entry in the data point library. This is used to find the default values for red and yellow ranges in case they are not configured for an individual object. Note that the unit which is set in the data point is not taken into account here.
3 Create alarm Type: Type of alarm being raised. It is strongly recommended to use different types of alarms for each smart rule. If the same alarm type is used across multiple smart rules, smart rules may interfere when trying to update the same alarm type, which might lead to unexpected behavior.
Text: Alarm message.
4 Target asset or devices Select a group or device the rule shall be applied to. To activate the smart rule in other assets or devices, navigate to the respective objects and enable the smart rule. The smart rules details will show a list "Active for target asset or devices".
If you leave this field empty, the smart rule will be applied to every group and device. You can then deactivate the smart rule for specific assets or devices. In this case the smart rules details will show a list "Inactive for target asset or devices".
For details on enabling/disabling a smart rule, see To enable/disable a smart rule for a group or device.

Description

For each incoming measurement value, the rule performs the following steps:

If no red/yellow ranges are defined in the merged parameters, no alarms are generated.

Info
Range values defined in the source object have a higher priority than those defined in the data point library. You can also just overwrite a single value (for example yellow range max) by setting it in the source object. The other values will then be taken from the Data Point Library.

Troubleshooting

Info
  • If you clear an alarm, you state that the alarm is resolved. A new alarm is not raised unless the device changes its state and exceeds the thresholds again.

  • Under certain circumstances, that means, if the time gap between measurements is quite large, this smart rule may raise a wrong alarm severity. If, for example, the CEP/Apama pod is restarted, the internal state is lost and therefore an alarm is raised again when it should not, resulting in a different alarm severity.

On measurement explicit threshold create alarm

Functionality

If the measurement value enters or leaves the red range, a CRITICAL alarm is generated or cleared.

The severity of alarm is determined as follows:

Info
This rule is similar to the rule “On measurement threshold create alarm”. However, in this rule here the red threshold value is provided explicitly. The threshold rule “On measurement threshold create alarm” extracts the thresholds values from the device or data point library.

Parameters

The rule uses the following parameters:

Step Field Description
1 Rule name Pre-filled with the name of the rule template. Can be modified according to your needs.
2 On threshold Fragment/Series: Name of the measurement fragment and series. The incoming measurement must have exactly the same fragment name as configured. When creating a rule from the data explorer, these fields are already filled in.
Minimum, Maximum: When a value is in the specified range [minimum; maximum], the configured alarm is raised.
3 Create alarm Type: Type of alarm being raised. It is strongly recommended to use different types of alarms for each smart rule. If the same alarm type is used across multiple smart rules, smart rules may interfere when trying to update the same alarm type, which might lead to unexpected behavior.
Text: Alarm message.
4 Target asset or devices Select a group or device the rule shall be applied to. To activate the smart rule in other assets or devices, navigate to the respective objects and enable the smart rule. The smart rules details will show a list "Active for target asset or devices".
If you leave this field empty, the smart rule will be applied to every group and device. You can then deactivate the smart rule for specific assets or devices. In this case the smart rules details will show a list "Inactive for target asset or devices".
For details on enabling/disabling a smart rule, see To enable/disable a smart rule for a group or device.

Troubleshooting

Info
  • If you clear an alarm, you state that the alarm is resolved. A new alarm is not raised unless the device changes its state and exceeds the thresholds again.

  • ​Under certain circumstances, that means, if the time gap between measurements is quite large, this smart rule may raise a wrong alarm severity. If, for example, the CEP/Apama pod is restarted, the internal state is lost and therefore an alarm is raised again when it should not, resulting in a different alarm severity.

Smart rule variables

In certain rule parameters, various trigger fields can be used as variables. When a rule is triggered, the variables are replaced by the actual values of these trigger fields.

You can use this mechanism for example to insert device names or alarm text into various outputs (email, SMS).

Common fields to be used from all triggers (alarms, measurements, operations, events)

Variable Content
#{id} Identifier of the trigger.
#{type} Type of the trigger.
#{source} Identifier of the source of the trigger.
#{time} Timestamp of the trigger.
#{text} Text or message of the trigger.
Info
If using Apama for smart rules (shown by a subscription to Apama-ctrl in Applications > Subscribed Applications in the Administration application), variables for times can include a time zone and time format to display the time in. The variable #{time:TZ=America/New_York,FORMAT=“HH:mm:ssZ”} for example displays the time using the time zone for New York in the format HH:mm:ssZ. See also Supported time zones and Format specification for the TimeFormat functions in the Apama documentation.

Fields specific for alarms

Variable Content
#{status} Status of the alarm: ACTIVE, ACKNOWLEDGED or CLEARED.
#{severity} Severity of the alarm: CRITICAL, MAJOR, MINOR or WARNING.
#{count} Number of times the alarm has been sent. Repeating alarms for the same device and same alarm type are de-duplicated into one alarm.

Fields specific for operations

Variable Content
#{status} Status of the operation: SUCCESSFUL, FAILED, EXECUTING or PENDING.

Fields specific for measurements

Variable Content
#{valueFragment} Measurement value fragment name.
#{valueSeries} Measurement series fragment name.
#{value} Value from the sensor.
#{unit} Unit being used, for example "mm", "lux".

Moreover, the following pattern is supported:

Variable Content
#{X.Y} or #{X.Y.Z} The property field information available in extra params or nested structure params of the trigger.

Example

Cumulocity IoT trigger

{
  "source":{
    "id":"10200"
  },
  "type":"TestEvent",
  "text":"sensor was triggered",
  "time":"2014-03-03T12:03:27.845Z",
  "c8y_Position":{
    "lat":2,
    "lng":2
  },
  "c8y_evtdata":{
    "data1":111,
    "date2":222,
    "evtInnerData":{
      "indate1":333,
      "indate2":444
    }
  }
}

Here we can for example define the following variables:

Variable Content
#{ c8y_Position.lat} Gets latitude value.
#{ c8y_evtdata.data1} Gets data1 value.
{ c8y_evtdata. evtInnerData . indate1} Gets nested structure value.
#{source.X.Y} The property field information from the source device (ManagedObject) of the trigger. For example:
#{source.c8y_Hardware.serialNumber} > Serial number of the device.
#{source.c8y_Notes} > Note field of the device.
Important
In case the variable does not exist or is misspelled, no substitution will occur.

Configuring Cockpit applications

Cumulocity IoT offers you to configure custom Cockpit applications according to your individual needs.

Requirements

To use the Cockpit configuration functionality, the following requirements have to be met:

  • You must have ADMIN permission for the permission type “Application management”.

  • The Cockpit application can only be configured if it is owned by the tenant. That means that you first have to create an own Cockpit application by duplicating the existing Cockpit application. For details, how to clone an application see Managing applications > Custom application > To add a custom application.

If these requirements are met, an App configuration entry is visible in the Configuration menu in the navigator of the custom Cockpit application.

To configure a custom Cockpit application

In the navigator, click App configuration in the Configuration menu.

App configuration

In the App configuration page, you can customize your Cockpit application in various aspects.

Features

In the Features section, you can disable certain features like for example, the global search, alarms, or the data explorer.

By default, all features are enabled. Use the toggle next to a feature to disable it. The respective menu item in the navigator (or the respective button as in case of the global search button) will immediately be removed and the functionality will no longer be available, until enabled again.

Top level nodes

Under Top level nodes you can select which groups to display on top level in the navigator. By default, only the Groups entry is shown (if not disabled in the Features section).

Nodes configuration

On the right, select the root groups or subgroups to be displayed as top level nodes in the navigator. Once selected, the group will be added to the custom top level nodes list. Moreover, you can further configure the nodes by enabling/disabling the display of devices for a certain group. If disabled, all devices for this group will be hidden, that is, not shown in the navigator.

Home dashboard

In the Home dashboard section, you can select how the home dashboard, that is, the landing page for this application, is treated.

You can select one of the following options for the customization of the home dashboard:

Info
The initial home dashboard shows a number of pre-installed widgets. These widgets can be changed according to your needs.

Click Reset dashboard to undo any changes to your home dashboard. This reverts all changes to the dashboard and returns it to the initial state.

To hide the navigator

Finally, you can specify if the navigator should be hidden on start up. By default, the navigator is displayed on start up.