Basic functionality

Developing applications

You can develop Apama EPL applications in two different ways:

See also Using the Apama Event Processing Language (EPL) in the Concepts guide.

Developing applications with Apama EPL Apps

Apama EPL Apps provides an interface for interactively editing new or existing EPL applications (*.mon files) as well as importing and activating (deploying) EPL applications.

Any user on the tenant wishing to use Apama EPL Apps will need to be a CEP Manager. See Managing permissions in the User guide.

Info: To be able to develop applications with Apama EPL Apps and/or to import them from Software AG Designer into Cumulocity IoT, your tenant needs to be subscribed to both the Apama-ctrl microservice and the Apama EPL Apps web application provided in Cumulocity IoT. If you have Apama Starter, Apama EPL Apps is not available in the application switcher. If you want to have this capability, contact Software AG support.

Step 1 - Invoke Apama EPL Apps

Open the application switcher and click the icon for the Apama EPL Apps application.

When you invoke Apama EPL Apps, the EPL application manager is shown first, listing any existing EPL applications. Each application is shown as a card. You can add new EPL applications and manage existing EPL applications from here.

Apama EPL Apps

Each card that is shown for an application has an actions menu at the top which allows you to edit or remove the application.

From this page, you can:

Step 2 - Create an EPL application

Click New EPL app in the top menu bar. Give the application a unique name. You can also enter a description which will be shown on the card that is created for the new application.

The EPL editor is shown next. The EPL code for the new application already contains the typical basic event definitions and utilities that are required for working with Cumulocity IoT. You can adapt them as required for your application. Consult the documentation and samples for more details.

EPL editor

To help you get started, several samples are available. To see them, click Samples which is shown to the right of the editor. Click on a sample to see a preview of its contents. You can select part of the sample code and copy it over into your own code using the standard key combinations Ctrl+C and Ctrl+V. You can also use the command buttons to copy the entire code to the clipboard and insert it at an appropriate position in your own code, or to replace all of your existing code with the sample code.

Using the buttons in the top menu bar, you can undo/redo your last changes in the current session and you can save your changes.

It is also possible to change the mode from Inactive to Active (or vice versa) in the EPL editor. Again, when there is an error in your EPL code, it is not possible to activate the application. The errors are highlighted within the code.

Keep the following in mind while creating (or importing) an EPL application: When an EPL application is activated, it is possible that some EPL operations are performed that are not allowed for the user who created the application. For example, you may only have ADMIN permission for “CEP management” for injecting EPL and creating Analytics Builder models. However, when the application is activated, it is also possible that the injected EPL can create or clear an alarm and that an Analytics Builder model can create an operation.

Side note: Be aware that the EPL editor makes use of a standard web component. It provides many generic developer functions, some of which are not relevant to EPL, including but not limited to Quick Fix and Show Hover.

Click X in the top menu bar to leave the EPL editor and thus to return to the list of EPL applications.

Caution: All unsaved changes are lost when you navigate to a different URL or close the browser window.

Step 3 - Test the EPL application

Once your application is activated, you should be able to see the results of it running. This may include sending measurements, receiving data, creating alarms, and logging in the Apama-ctrl microservice. For information on how to check the log files of the Apama-ctrl microservice, see Managing applications in the User guide.

See also Deploying applications.

Developing applications with Software AG Designer

Software AG Designer provides a full development environment and is the tool of choice when you have a complex EPL application. When your EPL application is ready, you then need to import it into Cumulocity IoT.

Step 1 - Install Apama

If you have licensed Apama, install it using Software AG Installer.

You can also use a freemium version of Apama which runs with reduced capabilities and several restrictions. If you want to use this, download the Apama Community Edition from http://www.apamacommunity.com/downloads/ and install it.

Both versions, the licensed version and the freemuim version, include Software AG Designer.

Step 2 - Create a project

Once installed, create an Apama project in Software AG Designer and enable it for Cumulocity IoT connectivity. For instructions on how to create an Apama project, refer to Creating Apama projects in the Apama documentation.

Step 3 - Add Apama bundles to the project

Add the following Apama bundles to the newly created Apama project. These are required by Cumulocity IoT so that it can activate your application. For instructions on how to add bundles to a project, refer to Adding bundles to projects in the Apama documentation.

The bundles above are the only ones that are permissible in an EPL application, so be careful not to add any other bundles or your application may not work when activated in Cumulocity IoT.

Step 4 - Create an EPL application

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

Before you import the newly created EPL application to Cumulocity IoT and activate it there, you might want to test if this application works as expected from within Software AG Designer.

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

Step 5 - Run and test the EPL application

When running the project locally, you will need to provide your Cumulocity IoT credentials in the project configuration. Configure the credentials in the CumulocityIoT.properties file under the Cumulocity client. For example:

CUMULOCITY_USERNAME=user@example.com 
CUMULOCITY_SERVER_URL=http://exampleTenant.cumulocity.com 
CUMULOCITY_PASSWORD=examplePassword 
CUMULOCITY_APPKEY=apamaAppKey

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

Note that the above description assumes that you are connecting to a tenant where the URL identifies the tenant. If that is not true (for example, if you are connecting by an IP address), you may need to set this in the CumulocityIoT.properties file:

CUMULOCITY_TENANT=my_custom_tenant

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

Once the EPL application is ready, refer to Deploying applications to find out how to deploy it to Cumulocity IoT.

Deploying applications

There are two distinct approaches to deploy Apama applications to Cumulocity IoT:

Info: In Apama EPL Apps, the term “activate” is used for deploying an application.

Deploying Apama applications as single *.mon files with Apama EPL Apps

Info: To be able to deploy single *.mon files with Apama EPL Apps, your tenant needs to be subscribed to both the Apama-ctrl microservice and the Apama EPL Apps web application provided in Cumulocity IoT. If you have Apama Starter, Apama EPL Apps is not available in the application switcher. If you want to have this capability, contact Software AG support.

When an Apama EPL application is activated in Cumulocity IoT, each *.mon file is assigned a unique package name. This prevents conflicts when multiple modules are activated. 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.

There is a restricted set of utilities and base events available for your EPL application. At the time of writing, these include the Time Format and HTTP Client > JSON with generic request/response event definitions bundles.

When any EPL application signals a runtime error, this will be raised as an alarm. Runtime errors include uncaught exceptions, as well as any explicit logging of warnings and errors that your EPL application chooses to do. Health issues that relate to the Apama runtime in general will also be raised as alarms.

For more detailed diagnostics of the Apama runtime and any active EPL applications, you can look at the logs for the Apama-ctrl microservice. See Managing applications in the User guide for more information on log files. However, some familiarity with Apama is necessary to get the most out of an Apama log file.

Deploying Apama applications as microservices

Using Software AG Designer, you can also develop more complex projects which:

These kinds of applications should be deployed as microservices to Cumulocity IoT.

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

Required settings in the microservice manifest

The microservice manifest provides the required settings to manage microservice instances and the application deployment in Cumulocity IoT. For detailed information, see Microservice manifest in the Microservice SDK guide.

Apama can only be used in a single-tenant microservice. Therefore, the microservice manifest must set the isolation level to PER_TENANT. The reason for this is that Apama’s Cumulocity IoT transport connectivity plug-in can only communicate with the tenant to which it is deployed. Therefore, having an Apama shared between multiple tenants is invalid.

Specific permissions are required by the microservice to start up and work properly. These are set with requiredRoles in the microservice manifest. The minimum set of permissions is the following:

To deploy an Apama application as a microservice

  1. Develop your Cumulocity IoT application in Software AG Designer in the usual way.

  2. 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 on Docker Hub. You will need Docker Hub credentials that give you access to the Apama images. Apama Docker images are exclusively Linux-based.

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

  4. Use the Cumulocity IoT microservice utility tool for packaging and deploying the project; for detailed information, see Microservice utility tool in the Microservice SDK guide. When creating the directory structure for the microservice utility tool to build from, copy your entire project directory inside that directory with the name “docker/”. For example:

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

    You have to create the microservice manifest manually, but 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). Enabling auto-scaling is not recommended, as Apama applications are usually stateful and do not automatically partition their input.

    You can pack, deploy and subscribe from this directory, resulting in your Apama application being turned into a running microservice. The behavior of the application when being run outside of Cumulocity IoT (from Software AG Designer or your test environment) will be near-identical to its behavior inside Cumulocity IoT. When deployed as a microservice doing requests to the Cumulocity API, Apama will automatically pick up the credentials to connect to the tenant you deployed it to, overwriting any other credentials provided to Apama. However, if you wish to receive real-time events, you will need to have valid credentials specified in the project configuration as you do when connecting to Cumulocity IoT from an external Apama environment.

  5. When you are ready to deploy to Cumulocity IoT, upload the application as a microservice. For details, refer to Administration > Managing applications in the User guide.

Events and channels

In Apama EPL, interactions with the rest of the Cumulocity IoT ecosystem are done via events. A number of event definitions is provided for accessing Cumulocity IoT data.

Predefined event types

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

Look at the data model in the API Reference for EPL (ApamaDoc) 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 IoT. 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.

Standard event types and channels

For the standard Cumulocity IoT events, there are constants that contain the channels for sending and receiving events, for example:

monitor.subscribe(Measurement.CHANNEL);
send msmnt to Measurement.CREATE_CHANNEL;
Event Channel for sending Channel for receiving
Operation Operation.CHANNEL Measurement.CHANNEL
Measurement Measurement.CREATE_CHANNEL Measurement.CHANNEL
Event Event.CHANNEL Measurement.CHANNEL
Alarm Alarm.CHANNEL Measurement.CHANNEL
ManagedObject ManagedObject.UPDATE_CHANNEL ManagedObject.CHANNEL

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 a *.mon file 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 *.mon file 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;
		}
	}
}