Introduction

Overview

Using the Cumulocity real-time event processing, you can add your own logic to your IoT solution. This includes data analytics logic but it is not limited to it. To define new analytics, you can use the Apama Event Processing Language - see the topic Developing Apama Applications in EPL in the Apama documentation for full details. The language allows analyzing incoming data. You can create, update and delete your data in real-time.

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

In the following sections, we describe the basics for understanding how the Apama Event Processing Language (EPL) works and how you can create your own analytics or other server-side business logic and automation.

Deploying EPL

You can use Software AG Designer to develop your applications. Create an Apama project in Software AG Designer and add the following connectivity bundles:

  • Cumulocity Client (of the appropriate platform version)
  • Utilities for Cumulocity (of the same version as the Cumulocity Client)
  • HTTP Client - JSON with generic request/response event definitions

Also add the following bundle by selecting it from the standard bundles:

  • Time Format

You will need to provide your Cumulocity credentials in the configuration files, thus in your Apama project go to config > connectivity -> CumulocityIoT and configure the credentials as follows in CumulocityIoT.properties file:

CUMULOCITY_USERNAME=user@example.com
CUMULOCITY_TENANT=exampleTenant
CUMULOCITY_PASSWORD=examplePassword
CUMULOCITY_APPKEY=apamaAppKey

Info: You need to create an application in Cumulocity to get a value for CUMULOCITY_APPKEY, see below.

Develop and test your EPL in Software AG Designer.

Deploying Apama applications as a single .mon file

When you are ready to deploy to Cumulocity, upload the .mon file containing your application through the Own applications page in the Administration application. For details, refer to Administration > Managing applications.

Info: To be able to upload custom EPL rules as applications to Cumulocity you need to be subscribed to the application "apama-small".

When the EPL is deployed to Cumulocity, each .mon file is assigned a unique package name. This prevents conflicts when multiple modules are uploaded. For this reason, you should not specify a 'package' statement in the .mon files. If you need to share events between different parts of your application, then write the event definitions and monitors that use it in a single .mon file.

Deploying Apama applications as microservices

You may also develop more complex projects which:

  • are spread across multiple .mon files
  • need to be isolated from other Apama applications
  • use connectivity plug-ins or EPL plug-ins that are not enabled by default

These kinds of applications should be deployed as microservice to Cumulocity.

**Info**: This only applies if you are using Apama 10.3 or later.

Develop your Cumulocity application in Designer in the usual way (just as shown above).

Next, you can use Apama's Docker support to turn the entire project into a microservice. In the Project Explorer view, right-click the project and select Apama > Add Docker Support, which will add a Dockerfile to the root of your project directory. When used for building, it will make use of the Apama images available in the Docker Store. You will need Docker Store credentials that give you access to the Apama images.

Add any custom steps to the Dockerfile that might be necessary e.g. building a custom plug-in, or copying your license file into the image.

Use the Cumulocity microservice utility for packaging and deploying the project, see Microservice package and deploy in the Reference guide. When creating the directory structure for the 'microservice' tool to build from, copy your entire project directory inside that directory with the name "docker/" e.g.

docker/monitors/
docker/eventdefinitions/
docker/Dockerfile
docker/...
cumulocity.json

There is no need for anything special in the microservice manifest; no roles or probes are required. However, if you want to configure a liveness or readiness probe, you can configure an 'httpGet' probe for the path '/ping' on port 15903 (Apama's default port).

You can pack, deploy and subscribe from this directory, resulting in your Apama application being turned into a running microservice. The behaviour of the application when being run outside of Cumulocity (from Designer or your test environment) will be near-identical to its behaviour inside Cumulocity. As Apama will be using identical Cumulocity configuration in both environments, make sure that the credentials and application key that you are using in your local environment are long-lived.

When you are ready to deploy to Cumulocity, upload the application as a microservice through the Own applications page in the Administration application. For details, refer to Administration > Managing applications.

Events and channels

In the Apama Event Processing Language, interactions with the rest of the Cumulocity ecosystem is done via events. A number of event definitions is provided for accessing Cumulocity data.

Predefined event types

There are some predefined event types to interact with several Cumulocity APIs. Events are sent to Apama applications automatically when a new measurement, alarm or event is created. For interacting with the Cumulocity backend, you can create an event and send it to the relevant channel. Cumulocity will automatically execute either the database query or create the API calls necessary for sending mails, SMS, or similar.

API Input events Output events Description
Inventory ManagedObject
FindManagedObjectResponse
FindManagedObject
This group of events represents lookup of ManagedObject objects.
Events Event Event This group of events represents creation or modification of a single event.
Measurements Measurement Measurement This group of events represents creation of a single measurement.
Device control
Operation This group of events represents creation or modification of a single operation.
Alarms Event
FindAlarmResponse
FindAlarm This group of events represents creation or lookup of a single alarm.
Emails (not used) SendEmail
This group of events represents sending of an email.
SMS (not used) SendSMS This group of events represents sending of an SMS.
Text-to-speech (not used) SendSpeech This group of events represents initializing of a phone call.
HTTP REST using JSON Response HttpTransport, Request Allows EPL to invoke a REST request on a remote site using JSON.

Look at the data model to see how the events for each stream are structured.

Sending events to a channel

Sending an event is done by constructing the event, either with new <type> followed by assignments to the fields, or with a constructor specifying all of the fields. The send statement is then used to send the event to Cumulocity. The send statement requires a channel - this is typically the CHANNEL constant (CREATE_CHANNEL for Measurement) on the event type.

Listening to events

You can trigger your EPL by listening to events on channels. You can subscribe to channels with the monitor.subscribe(string name) method. This can be done in the startup of your monitor, or if you only need to receive events some of the time, called as needed, followed by monitor.unsubscribe(). Listen for events using the on statement, followed by the event type that you are listening to, open and close parentheses, and as <identifier> to name a variable that will hold the event. By default, a listener will fire once; to make it repeat for all events, use the all keyword before the event type.

Filters

Adding filters can be done by specifying one or more fields between the parentheses for a listener. Only top-level fields can be filtered for. Use if statements for more complex filtering, or for filtering on sub-properties of events (for example, in dictionaries).

Example

As an example, we create a statement. The statement listens to one event and creates a different event type whenever the specified filter applies. For instance‚ we want to create an alarm for each temperature measurement that is created.

Info: In order to create the statement, first you have to create an "EPL Monitor" in your Apama project.

  1. Subscribe to Measurement.CHANNEL
  2. Listen to the measurement type - filtering on the type having the value "c8y_TemperatureMeasurement".
  3. Create the event using the constructor specifying all of the fields.
  4. Send the event to the correct channel - Alarm.CHANNEL.

The resulting monitor can look like this:

using com.apama.cumulocity.Alarm;
using com.apama.cumulocity.Measurement;

monitor ForwardMeasurements {
    action onload() {
        monitor.subscribe(Measurement.CHANNEL);
        on all Measurement(type = "c8y_TemperatureMeasurement") as m {
            send Alarm("", "c8y_TemperatureAlarm", m.source, m.time,
                       "Temperature measurement was created", "ACTIVE", "CRITICAL", 1, new dictionary<string,any>) to Alarm.CHANNEL;
        }
    }
}