About the Cumulocity IoT transport

For details on the support lifetime of the connectivity to Cumulocity IoT, refer to the Release Availability document for the current Apama version. This can be found in the list of guides for the current Apama documentation on the Software AG documentation website at https://documentation.softwareag.com/.

Apama provides several connectivity bundles which allow you to communicate with the IoT devices connected to Cumulocity IoT. For example, you can receive events from the devices, send operations to the devices, and query the state stored in the platform.

The following bundles are under the Cumulocity IoT group of connectivity bundles (see Adding bundles to projects for more information on connectivity bundles):

Cumulocity Client (includes REST support). This bundle is for the legacy real-time notifications feature and has been superseded by the Cumulocity Notifications 2.0 bundle.

Cumulocity Notifications 2.0 (includes REST support). This is the recommended way to receive events and updates as they are published from devices as well as query and publish data to the platform. This bundle replaces the Cumulocity Client bundle.

Note:
The Cumulocity Notifications 2.0 feature is currently in private preview. If you would like to have it enabled for your tenant, please contact Cumulocity IoT Operations.

Cumulocity REST Support. This bundle is for applications that do not need to receive real-time updates and only need to publish data or query the platform. You must not add it to your project if you are adding one of the other bundles.

When using Cumulocity Notifications 2.0, Apama creates subscriptions in Notifications 2.0 that persist after Apama has exited to allow processing of the event stream to be resumed later. This consumes the resources of the server. If a particular subscription name is no longer used, you must manually delete the subscription using the Notifications 2.0 REST API.

You configure the Cumulocity IoT connectivity bundles by editing the .properties files that come with the respective connectivity bundle. All bundles provide a .properties file for configuring the REST API connection. The Cumulocity Client and Cumulocity Notifications 2.0 bundles also provide a second .properties file with properties specific to that connection. See Adding the Cumulocity IoT connectivity plug-in to a project and Configuring the Cumulocity IoT transport for further information.

In addition to the above connectivity bundles, the following EPL bundles are also available (see also Adding EPL bundles to projects). These bundles are included automatically if you add any of the connectivity bundles.

Event Definitions for Cumulocity. This EPL bundle defines all events that can be used for interacting with Cumulocity IoT. This includes definitions for events that you receive from Cumulocity IoT, events that you can send to Cumulocity IoT, and event APIs that you can use for requesting data from Cumulocity IoT. For more information, see the com.apama.cumulocity package in the API Reference for EPL (ApamaDoc) .

Utilities for Cumulocity. This EPL bundle contains useful utilities for EPL code that is interacting with Cumulocity IoT. It also contains a geofence helper utility for determining whether a location is part of a geofence or not. For more information, see the com.apama.cumulocity.Util and the com.apama.cumulocity.GeoFenceContainer events in the API Reference for EPL (ApamaDoc) .

In addition to using Software AG Designer to add the above mentioned connectivity and EPL bundles, you can also do this using the apama_project command-line tool. See Creating and managing an Apama project from the command line for more information.

The samples/cumulocity directory of your Apama installation includes samples which show how to use the Cumulocity IoT bundles. For more information, see the README.txt file in the corresponding samples folder.

As with other connectivity plug-ins, the EPL application should call com.softwareag.connectivity.ConnectivityPlugins.onApplicationInitialized(). For more information, see Sending and receiving events with connectivity plug-ins. Per-tenant EPL applications automatically start to receive Notifications 2.0 events after this call. Multi-tenant applications need to additionally send a com.apama.cumulocity.notifications2.SubscribeTenantNotifications event for each tenant to SubscribeTenantNotifications.SEND_CHANNEL to start receiving notifications from that tenant. For an example, see Working with multi-tenant deployments.