Introduction

Devices and sensors can be connected to Cumulocity IoT. See Interfacing devices and Device integration using MQTT.

Sensors result in Measurement or Event objects in Cumulocity IoT, and devices can receive Operation objects created within the Cumulocity IoT platform. All of these objects (Measurement, Event, Operation) will be associated with a single device in the Cumulocity IoT platform. A device may have multiple types of measurement associated with it, and the types of measurements each device supports may be the same as other devices or different to other devices. Once devices are connected to Cumulocity IoT, information about these devices is stored in the Cumulocity IoT inventory. These are visible in the Device management application, which can also be used to view Measurement, Event or Operation objects associated with that device. See Device management for more information.

Using the Streaming Analytics application, you can add your own logic to your IoT solution for immediate processing of incoming data from devices or other data sources. These user-defined operations can, for example, alert applications of new incoming data, create new operations based on the received data (such as sending an alarm when a threshold for a sensor is exceeded), or trigger operations on devices.

Typical real-time analytics use cases include:

  • Remote control: Turn a device off if its temperature rises over 40 degrees.
  • Validation: Discard negative meter readings or meter readings that are lower than the previous.
  • Derived data: Calculate the volume of sales transactions per vending machine per day.
  • Aggregation: Sum up the sales of vending machines for a customer per day.
  • Notifications: Send me an email if there is a power outage in one of my machines.
  • Compression: Store location updates of all cars only once every five minutes (but still send real-time data for the car that I am looking at to the user interface).

The Cumulocity IoT platform includes an Apama correlator component, which is managed by the Cumulocity IoT platform (this is not manually started or stopped) and is preconfigured to communicate to Cumulocity IoT. This correlator hosts the Analytics Builder runtime, and also executes any operation logic added using EPL apps. The operation logic is based on Apama’s Event Processing Language (Apama EPL).

The Streaming Analytics application can be used with both Cumulocity IoT Core (cloud) and Cumulocity IoT Edge (local installation).

Home screen

You access the Streaming Analytics application using the application switcher.

Streaming Analytics home screen

The home screen of the Streaming Analytics application lets you navigate to the different pages of the application. These are Analytics Builder and EPL Apps. You can access these pages using the corresponding Open button on the home screen or by using the navigator on the left.

If you need more space for a page, you can hide the navigator. Click the small arrow at the very left of the top bar to toggle the display of the navigator.

The home screen also provides information on smart rules. You create and maintain them with the Cockpit application. See Smart rules for detailed information.

The home screen and navigator only show entries for the items that you are allowed to use, depending on the version of the Apama-ctrl microservice to which your tenant is subscribed. See also Microservice runtime and applications and Customizing the home screen of the Streaming Analytics application.

Analytics Builder

The Analytics Builder page of the Streaming Analytics application allows you to build analytic models that transform or analyze streaming data in order to generate new data or output events. The models are capable of processing data in real time.

The models interact with the devices and sensor measurements. Models can receive Measurement and Event objects from devices, which provide the inputs to calculations or pattern detection performed within a model. Models can create new Measurement objects which can represent derived values from sensors (for example, an average temperature) or the measurements can be used as an input to other analytic models (see Connections between models). Models can create new Operation objects which are sent to devices to control the devices (for example, to sound an alarm bell, display a message on a screen, or switch a device off). The models are also stored in the Cumulocity IoT inventory, but can be imported or downloaded via the model manager.

You build the models in a graphical environment by combining pre-built blocks into models. The blocks in a model package up small bits of logic, and have a number of inputs, outputs and parameters. Each block implements a specific piece of functionality, such as receiving data from a sensor, performing a calculation, detecting a condition, or generating an output signal. You define the configuration of the blocks and connect the blocks using wires. You can edit the models, simulate deployment with historic data, or run them against live systems. See Analytics Builder for detailed information.

It is also possible to build custom blocks if none of the blocks delivered with Analytics Builder implement the logic required; see Creating your own blocks.

You can customize several aspects of Analytics Builder by setting various tenant options. See Configuration for detailed information.

EPL Apps

The EPL Apps page of the Streaming Analytics application allows you to write business logic in Apama’s Event Processing Language (Apama EPL) which gives more power and flexibility in a text-based programming language. This is an alternative if more complex logic is required or the logic does not fit into the pattern of an analytic model.

You can develop EPL apps (that is, single *.mon files) directly within Cumulocity IoT, written in Apama EPL. You can also import existing *.mon files as EPL apps into Cumulocity IoT. When you activate an EPL app from the Streaming Analytics application, you deploy it to Cumulocity IoT. See EPL Apps for detailed information, including examples.

A quick way to get started is to explore the code of the EPL samples that can be accessed from the EPL editor. See Developing apps with the Streaming Analytics application for information on how to create an EPL app and access the samples. For a start, use one of the simpler samples with temperature measurements, such as “Create an alarm if a measurement exceeds a threshold value”. You can immediately see results using this sample. Add your own EPL code to the sample and try out your changes.

You use the Apama API for interacting with Cumulocity IoT. For detailed information, see the com.apama.cumulocity package in the API Reference for EPL (ApamaDoc), which is part of the Apama documentation.

Prerequisites

Browsers

The Streaming Analytics application supports the same browsers as Cumulocity IoT, with the following exception: browsers on smartphones and tablets are not supported.

Permissions

To use Analytics Builder, you must at least have the following permissions:

Permission type Permission level
CEP management ADMIN
Option management READ
Inventory READ

This is typically achieved by using a global role which has those permissions, and where the role has access to the Analytics Builder application. See Managing permissions for details.

To use EPL Apps, you only need the following permission:

Permission type Permission level
CEP management ADMIN

Microservice runtime and applications

Analytic models, EPL apps and smart rules are executed in an Apama-ctrl microservice. All microservices come with pre-configured resource limits (for example, CPU and memory). The resource usage of analytic models, EPL apps and smart rules depends on various factors such as application complexity, number of devices, etc. It is recommended that customers profile their applications to avoid out-of-memory issues.

To do this you need the following
Build analytic models Apama-ctrl microservice variant (for example, Apama-ctrl-starter) and Streaming Analytics application
Develop EPL apps Apama-ctrl microservice variant (for example, Apama-ctrl-250mc-1g) and Streaming Analytics application
Use smart rules Any Apama-ctrl microservice variant and Smartrule microservice (included in Cumulocity IoT’s Standard tenant)

See also the following sections:

If your tenant is subscribed to the Apama-ctrl-starter microservice, then the following applies:

  • Limited number of at most 3 active analytic models. Custom blocks written with the Analytics Builder Block SDK cannot be used.
  • The EPL Apps page is not available in the Streaming Analytics application.
  • Smart rules are supported.

If your tenant is subscribed to the Apama-ctrl-250mc-1g microservice (or one of its larger variants), then the following applies:

  • Analytic models, EPL apps and smart rules are supported.
  • Custom blocks written with the Analytics Builder Block SDK can be used.

If your tenant is subscribed to the Apama-ctrl-mt-4c-16g microservice, then the following applies:

  • Multi-tenant support.
  • EPL apps are only enabled on the tenant that owns the microservice, but disabled on the subtenants.
  • The Analytics Builder page is currently not available in the Streaming Analytics application.
  • Smart rules are supported.

If your tenant is subscribed to the Apama-ctrl-smartrules or Apama-ctrl-smartrulesmt microservice, then the following applies:

  • Smart rules are supported.
  • The Analytics Builder and EPL Apps pages are not available in the Streaming Analytics application.

Contact product support to discuss adding more capabilities.

Language settings

The language in which the user interface of the Streaming Analytics application is shown depends on your user settings in Cumulocity IoT. See User options and settings for more information.

If Cumulocity IoT or the browser is set to a language that is currently not supported by the Streaming Analytics application, the user interface is shown with the default language, which is English.