Best practices and guidelines

EPL monitors

Symptom: Your event processing rules are disabled automatically

If a monitor throws an exception from onload or a listener and the exception is not caught, then the monitor will be terminated. Catch exceptions or avoid the reason for them occurring.

Similarly, if a monitor completes processing an event and has no listeners left active, then it cannot be triggered again, and will automatically remove itself.

Avoid excessive memory usage per monitor

Make sure that your event processing rules do not leak listeners. For example, when doing request-response operations, ensure that no listeners are left active after the response is processed, or if a timeout occurs and there is no response.

Number formats

Cumulocity measurements use the decimal type. When using numeric literals in your code, you must append a "d" character to use as a decimal. Alternatively, convert to float with .toFloat() (or float to decimal with float.toDecimal()). Note that the timestamps are stored as floats (seconds since 1 Jan 1970, 00:00 UTC).

Apama limitations in Cumulocity IoT

Using Apama within the Cumulocity IoT environment necessarily has some restrictions to the capabilities available when Apama is used standalone.

There are a number of ways that assets may be deployed to Apama within Cumulocity IoT and the restrictions vary according to those mechanisms:

When designing an Apama solution to be deployed within any form of Cumulocity IoT environment, consider the following points.

General Apama limitations when using “Upload custom Apama rule” or “Custom microservice”

  • For scalability, a correlator may move between hosts and therefore does not have access to a persistent file system. It is a standard Cumulocity IoT constraint that all microservices (either provided by the platform, or custom) must be stateless – see Developing applications > Cumulocity microservices in the Concepts guide.

    The Apama features affected by this include:

    • Correlator persistence.
    • MemoryStore persistence.
  • Non-HTTP/REST connections to an external system or process are mostly impractical. Although if a service is available over the internet then it can be used (for example, an HTTP client inside Apama could connect to publicly accessible HTTP servers).

    The Apama features affected by this include:

    • Apama Database Connector (ADBC).
    • Correlator-integrated support for the Java Message Service (JMS).
    • Software AG Digital Event Services.
    • Distributed memory stores.
    • Connections between correlators.
  • For security and implementing user access control, Cumulocity IoT does not make the correlator port available to external processes – see Developing applications > Cumulocity microservices in the Concepts guide.

    The following capabilities require access to the correlator port and hence are not compatible with this access control:

    • Command line tools such as engine_connect, engine_management, engine_send, engine_receive.
    • EngineManagement API, EventService API, ScenarioService API.
    • Connecting to adapters running out-of-process in an IAF.
    • Dashboards (provided in-the-box with Apama).
    • Debugging from Software AG Designer. Instead, debug your application running in a local correlator.
    • Correlator REST interface.

Specific Apama limitations when using “Upload custom Apama rule”

  • For ease of use, the correlator startup is controlled by Cumulocity. Thus, features that require you to change configuration files or command line options are not accessible.

    The Apama features affected by this include:

    • Persistence.
    • Connectivity plug-ins.
    • Management via Command Central.
  • For security, the file system used by the correlator is not accessible.

    The Apama features affected by this include:

    • Accessing the correlator log file or input log.
    • Using custom plug-ins.
    • Using file system assets for enrichment.
  • For simplicity, it is only possible to make independent EPL injections. Each monitor is managed independently and so dependencies between different monitors cannot be created.

    The Apama features affected by this include:

    • A .mon file must not contain a package statement (to do so is an error).
    • It is not possible to share event definitions between separate .mon files.
    • It is not possible to use Apama queries.
    • You can only use the bundles listed in Introduction -> Deploying EPL. This includes:
      • Cumulocity IoT Event Definitions
      • JSON with generic request/response event definitions

All of these restrictions are implemented to ensure the smooth and secure operation of Apama applications within Cumulocity IoT.