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.

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.

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

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

Deploying Apama applications as a single *.mon file with the Apama-epl application

Info: To be able to upload single *.mon files to Cumulocity, your tenant needs to be subscribed to both Apama applications provided in Cumulocity. See applications in the Reference guide for details.

The Apama-epl application provides an interface for uploading and deploying EPL apps (*.mon files), as well as interactively editing new or pre-existing EPL apps. Any user on the tenant wishing to use this application will need to be a CEP Manager. See managing permissions.

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.

When any EPL app 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 app 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 apps, you can look at the logs for the “apama-ctrl” microservice. See log files for more details. However, some familiarity with Apama is necessary to get the most out of an Apama log file.

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.

Deploying Apama applications as microservices

You may also develop more complex projects which:

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

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

To deploy an Apama application as microservice

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

  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 in the Docker Store. You will need Docker Store 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 e.g. building a custom plug-in, or copying your license file into the image.

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

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

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

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;
        }
    }
}