Basic functionality

Developing applications

Follow these steps to develop applications.

Step 1 - Install Designer

You can use Software AG Designer to develop your applications. Download and install Software AG Designer from the Apama Community.

Step 2 - Create a project

Once installed, create an Apama project in Software AG Designer and enable it for Cumulocity connectivity.

For steps on how to create an Apama project, refer to Creating Apama Projects.

Step 3 - Add Apama bundles to the project

Add the following Apama bundles to the newly created Apama project. For instructions on how to add bundles to a project, refer to Adding bundles to projects.

  • Cumulocity IoT > Event Definitions
    Provides event APIs required for sending and receiving data to/from Cumulocity IoT.
  • Cumulocity IoT > Utilities for Cumulocity
    Provides helper utility functions for working with data received from Cumulocity IoT.
  • Any Extractor
    Provides support for extracting values from the any type.
  • Time Format
    Required to access all the methods of the Time Format plug-in. Useful for formatting and parsing Time.
  • HTTP Client Generic Events
    Exposes pre-defined generic events used by the HTTP client connectivity plug-in.

Step 4 - Create sample EPL application

To create a new Apama EPL file, refer to Creating new monitor files for EPL applications.

Follow the steps as described in Using EPL to create a sample EPL application.

Before you deploy this EPL application to Cumulocity, you might want to test if this application works as expected. To do so, you need to add the following bundles to your Designer project.

  • Add Automatic onApplicationInitialized
    This starts all connectivity plug-ins immediately on start up.
  • Add the HTTP Client > JSON with generic request/response event definitions connectivity transport.
  • Add the Cumulocity IoT > Cumulocity Client connecitivity transport.

For further information on The Cumulocity IoT Transport Connectivity Plug-in, see the Apama documentation.

Step 5 - Provide credentials

You will need to provide your Cumulocity credentials in the project configuration. Configure the credentials in the CumulocityIoT.properties file under the Cumulocity client as follows:

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.

Note that the above description assumes that you are connecting to a tenant hosted on cumulocity.com (Example: mytenant.cumulocity.com). If you want to connect to a tenant hosted at a different location, you can append a custom URL configuration to CumulocityIoT.yaml.

url: ${CUMULOCITY_URL}

and append the URL details in CumulocityIoT.properties:

CUMULOCITY_URL=my_custom_tenant.mydomain.com

You can now proceed with testing your EPL in Software AG Designer.

Once the EPL application is ready, refer to Deploying applications to upload the EPL application as a single .mon file.

Deploying applications

Deploying Apama applications to Cumulocity

To be able to upload custom EPL rules as applications to Cumulocity you need to be subscribed to one of the Apama applications provided in Cumulocity, see also the list of available applications in the Reference guide.

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.

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.

The only non-Cumulocity bundles that your EPL is able to use are the Time Format bundles and the HTTP Client - JSON with generic request/response event definitions.

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.

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 (the exceptions being CREATE_CHANNEL for Measurement and UPDATE_CHANNEL for ManagedObject) 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("string name"). 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, currentTime,
                        "Temperature measurement was created", "ACTIVE", "CRITICAL", 1,
                        new dictionary<string,any>) to Alarm.CHANNEL;
        }
    }
}