Cockpit

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.

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.

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.

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:

The asset hierarchy is composed of two types of objects:

• Groups: Objects which group single devices or other groups. Groups can either be created in the Cockpit application or in the Device Management application.

• Devices: Devices which are linked into the asset hierarchy. Before you can use devices in the Cockpit application, they must be connected to Cumulocity IoT. This is done in the Device Management application. For details on connecting devices refer to Connecting Devices in the Device Management section.

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).

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:

• Smart devices are self-contained devices that include sensors, actuators and a communication module. They are typically connected to a single asset. Smart devices are trackers, weather stations or general “smart” sensors with a built-in communication module.

• Gateway devices establish the communication from other devices to Cumulocity IoT but do not include sensors or actuators. Typical gateway devices include Zigbee, Modbus, M-Bus or KNX gateways.

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:

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.

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.

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:

• Subassets - Shows group details and all subassets of a group, see also Device management > Viewing devices.
• Smart rules - Shows smart rules specified for the group, see also Smart rules.
• Data explorer - Shows all data points of the children. For details refer to Visualizing data using the data explorer.

Devices show the following tabs:

• Smart rules - Shows smart rules specified for the device, see also Smart rules.
• Alarms - Displays alarms for the device, see also Device management > Working with alarms.
• Data explorer - Shows all data points of the children. For details refer to Visualizing data using the data explorer.
• Location - Shows the current location of a device (only available with c8y_Position).

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.

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.

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

• Click Data explorer in the navigator to visualize all data points of all assets.

• Navigate to a particular asset and switch to the Data explorer tab to visualize all data points of this particular asset and its subassets.

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.

The visualization is generated based on data point properties.

The data points properties are pre-filled as follows:

• If these properties have been customized previously, these values are used, see Customizing data point properties.

• If the data points have a matching definition in the data point library, the values from the data point library are used.

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.

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:

• Select a different time range from the dropdown list in the top menu bar.
• Enter a custom time range into the From and To fields in the data explorer.
• Drag the x-axis and move left or right to move the time period.
• Double-click into the data explorer to zoom out.

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:

• If no aggregation is selected the date, hour, minute and second are shown:
  27 Jan 2020 17:26:55
• If minutely aggregation is selected, the second indication will not be shown:
  27 Jan 2020 17:27-17:28
• If hourly aggregation is selected, the minute and second indication will not be shown:
  27 Jan 2020 05:00-06:00
• If daily aggregation is selected, only the day will be shown:
  27 Jan 2020-28 Jan 2020.

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.

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:

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:

• Two data points having the same minimum and the same maximum value.

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.

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.

Exporting measurement data

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

• Time when the specific measurement was taken
• Source of the measurement
• Name of the device being used
• Fragment series (for example c8y_SpeedMeasurement)
• Value of the measurement
• Unit used for a particular measurement (for example “C”, “km/h”, “sec”)

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.

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.

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.

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.

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.

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.
   
   
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.

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.

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.

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.

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.

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.

Full text search

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.

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.

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:

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.

Parameters to configure

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.

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.

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.

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.

Parameters to configure

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

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.

The resulting table is visualized as follows:

To add properties

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

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.

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.

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

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.

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

• Auto-scroll on - When a new measurement arrives, the widget automatically scrolls to the top so that you can see the latest value.
• Auto-scroll off - When a new measurement arrives, the display does not change and the table still shows the same snippet of data.

Event list

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

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.

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.

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

• Target assets or devices: Select the objects for which optional HTML expressions are evaluated.

• HTML code

  The following variables can be used inside the HTML content:

  • {{devicesCount}}: Total number of devices.

  • {{usersCount}}: Total number of users.

  • {{deviceGroupsCount}}: Total number of groups.

  • {{device.name}}: The name of the device.

  • {{device.property}}: More general form of the above. You can address any property of the device.

  • {{device.c8y_Hardware.model}}: The model of the device.

  • {{device.fragment.property}}: More general form of the above. You can address any property of any fragment of the device.

  • {{devices[deviceId].name}}: The name of the device at the specified index.

  • {{devices[deviceId].property}}: More general form of the above. You can address any property of the device at the specified index.

“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:

• strict - Does not allow any JS or angularjs directives.
• lax (default) - Allows partly JS (events) and all angularjs directives.
• none - Allows everything.

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.

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.

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:

• Red = At least one CRITICAL alarm
• Orange = At least one MAJOR alarm
• Yellow = At least one MINOR alarm
• Blue = At least one WARNING
• Green = No alarm

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

• The device name. When clicked, the application navigates to the device.
• The date at which the device last reported its location, if available.
• A toggle to show/hide the device tracks for the previous and current days.

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.

Markdown

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

There are several ways to provide markdown content:

• Upload a markdown file.
• Provide a URL to an external source.
• Add “/README.md” as a relative file path in order to provide the README file of the current application as source.

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

Radial Gauge

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

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.

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

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:

• strict - Does not allow any JS or angularjs directives.
• lax (default) - Allows partly JS (events) and all angularjs directives.
• none - Allows everything.

Silo

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

Parameters to configure

Traffic light

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

Parameters to configure

Managing exports

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

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.

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).

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.

Fields

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

• Alarms
• Events
• Managed objects
• Measurements

Use the toggle to enable/disable a field.

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

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):

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.

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.

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}.”

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.

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.

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.

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

• Color and label for the data point
• Fragment name and series
• Measurement unit
• Values (minimum, maximum, red/yellow ranges)

To add a data point to the library

1. Click Add data point in the top menu bar.
2. Provide the following information:

3. 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).

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

• Rule parameters are provided by the user when creating a smart rule from a template. Examples are email addresses and alarm texts.
• Object parameters are stored in the group or device. These parameters can be edited after the smart rule has been created. An example includes min and max values for thresholds.

There are two different types of smart rules:

• Global smart rules

  Global smart rules are created in a global context (Smart rules page, alarms, data explorer, and so on).

• Local smart rules

  Local smart rules are created in either a group or a device. They are visible to everyone with access to the group/device.

Smart rules can be seen in two places:

• In the Global smart rules page accessible from the Configuration menu.

  

  In the Global smart rules page, only the global smart rules are shown.

• In the Smart rules tab of a device or group.

  

  In a local context (group or device) the local smart rules are shown. For users with the relevant permissions, both local and global smart rules are shown.

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.

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

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.

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.

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.

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:

On alarm send SMS

Functionality

If an alarm is created, an SMS is sent.

Parameters

The rule uses the following parameters:

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

• Verify that the alarm was created and not duplicated from somewhere.

• Check if the device is in maintenance mode. In this case no new alarm will be created because of suppression policy.

• If you have configured an alarm mapping rule (see Administration > Alarm mapping) which changes the alarm severity, the alarm may have different severity than expected.

On alarm send email

Functionality

If an alarm is created, an email is sent.

Parameters

The rule uses the following parameters:

• Verify that the alarm was created and not duplicated from somewhere.

• Check if the device is in maintenance mode. In this case no new alarm will be created because of suppression policy.

• If you have configured an alarm mapping rule (see Administration > Alarm mapping) which changes the alarm severity, the alarm may have different severity than expected.

• Check your spam folder.

On alarm escalate it

Functionality

If an alarm is created, sends email or SMS.

Parameters

The rule uses the following parameters:

Troubleshooting

• Verify that the alarm was created and not duplicated from somewhere.

• Check if the device is in maintenance mode. In this case no new alarm will be created because of suppression policy.

• If you have configured an alarm mapping rule (see Administration > Alarm mapping) which changes the alarm severity, the alarm may have different severity than expected.

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:

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.

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:

|

Troubleshooting

• Make sure the device was inside the geofence at least once after creating/activating the rule.

• Check if the device is in maintenance mode. No new alarm will be created because of suppression policy.

• If you have configured an alarm mapping rule (see Administration > Alarm mapping) which changes the alarm severity, the alarm may have different severity than expected.

On geofence send email

Functionality

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

Parameters

The rule uses the following parameters:

Troubleshooting

• Make sure the device was inside the geofence at least once after creating/activating the rule.

• Check your spam folder.

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:

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:

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:

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:

• If the measurement value moves into the red range, then an alarm of CRITICAL severity is created. If it moves out of the red range, the CRITICAL alarm is cleared.

• If the measurement value moves into the yellow range, then an alarm of MINOR severity is created. If it moves out of the yellow range, the MINOR alarm is cleared.

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

• Data point library red/yellow range: Red range when the system should create CRITICAL alarms and yellow range when the system should create MINOR alarms. Note that the data point should have at least one of red or yellow range configured.

• Object red range: Range when the system should create CRITICAL alarms. These values can be edited in the data explorer for each data point. Note that these are close intervals ([red min: red max]) that contain the lowest accepted value and the highest accepted value, see also examples below.

• Object yellow range: Range when the system should create MINOR alarms. These values can be edited in the data explorer for each data point. Note that these are half-open intervals ([yellow min : yellow max)) that contain the lowest accepted value but not the highest accepted value, see also examples below.

Examples

Example 1 - Red range:

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

• red min: 60
• red max: 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)”

• yellow min: 30
• yellow max: 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:

• red min: 60
• red max: 90
• yellow min: 30
• yellow max: 60

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]":

• red min: 50
• red max: 90
• yellow min: 30
• yellow max: 60

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:

Description

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

• Check if the smart rule has a valid data point. If not, an alarm with MAJOR severity is sent from the rule engine (CEP) informing that the rule has an invalid configuration.

• Check if the rule is activated for the source object.

• Check if the measurement includes data for the fragment and series (configured data point’s parameter).

• The data of the red and yellow range is collected from either:

  • The data point library (control parameter).
  • The source object (the measurement). If found, ranges from the source object’s data point override are merged.

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

• Incoming value inside the red range: If there is no active alarm of CRITICAL severity of given type for the object, create a CRITICAL alarm, else do nothing.

• Incoming value inside the yellow range: If there is no active alarm of MINOR severity of given type for the object, create a MINOR alarm, else do nothing.

• Measurement outside of yellow and red range: If there is an active alarm of given type for the object, clear the CRITICAL and/or MINOR alarm.

Troubleshooting

• Verify that the alarm was created and not duplicated from somewhere.

• Check if the device is in maintenance mode. In this case no new alarm will be created because of suppression policy.

• If you have configured an alarm mapping rule (see Administration > Alarm mapping) which changes the alarm severity, the alarm may have different severity than expected.

• Check if an alarm was already cleared by the next scheduled measurements with resulting value in a green range.

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:

• If the measurement value moves into red range, then the severity is CRITICAL.

• If the measurement value moves into GREEN range, no alarm is created.

Parameters

The rule uses the following parameters:

Troubleshooting

• Verify that the alarm was created and not duplicated from somewhere.

• Check if the device is in maintenance mode. In this case no new alarm will be created because of suppression policy.

• If you have configured an alarm mapping rule (see Administration > Alarm mapping) which changes the alarm severity, the alarm may have different severity than expected.

• Check if an alarm was already cleared by the next scheduled measurements with resulting value in a green range.

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)

Fields specific for alarms

Fields specific for operations

Fields specific for measurements

Moreover, the following pattern is supported:

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:

Configuring Cockpit applications

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

To configure a custom Cockpit application

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

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).

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:

• It is reflected throughout the entire tenant (the default).
• It is only reflected in the current custom application.
• It is only reflected in the current user. Note that this user then needs CREATE permission for the permission type “Inventory”.

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.