Apama Advent Calendar - 15 Dec 2021 - EPL in Cumulocity IoT


Previously, Day #6 of the Advent Calendar dealt with the fundamentals of Apama EPL (Event Processing Language) and Day #10 touched on Cumulocity IoT as one of several development environments. Today we deal with the Cumulocity IoT environment in more detail.

Regardless of how each Apama component is presented within the Cumulocity IoT UI, the underlying functionality will be written in EPL and run within an instance of the correlator. This is most obvious with the Streaming Analytics component “EPL Apps”, which provides a developer UI for direct code development.

The same is also true of the companion component “Analytics Builder” that was covered in Day #3. The UI for the Analytics Builder is graphical, composed of various functional blocks which can be wired together to compose complex analytics easily without needing any programming knowledge. However, under the hood, each block is written in EPL along with the framework which checks and wires the entire network together. Custom blocks can also be added, and these will be written using EPL. The details of this will be covered tomorrow.

Even more abstracted are the smart rules, available via the Cockpit application. These provide pro-forma rules via simple dialogs to carry out common, basic tasks. Nevertheless, the underlying execution of those rules is again EPL running in an Apama correlator instance.

EPL Apps

So let’s take a closer look at EPL Apps, the app that exposes you to EPL directly.

Your initial view will be the grid that shows all the existing EPL apps that are currently available within Cumulocity IoT, along with their status of Active or Inactive. Active apps are those which have been injected into and are currently running within the correlator. From each tile, via the three-dot menu, it is also possible to Export or Remove an app. Exporting creates a standard EPL file of the type you would create from within Software AG Designer or Visual Studio Code, and can be created or edited there if you wish. Once finished these apps can be imported back into EPL Apps.

An EPL app that contains compile-time errors cannot be activated and will show an error on its tile after you have attempted an activation.

An app can be opened for editing simply by clicking on its tile. Note that editing an active app will require the app to be reactivated for the changes to be saved. Ideally, an EPL app will be stateless due to the way Cumulocity IoT ensures scalability, so reactivation should have little impact. This is however a limitation of EPL within Cumulocity IoT compared to its use in a standalone correlator that can implement persistence. There are some other limitations imposed on EPL apps due to the Cumulocity IoT environment, including an inability to use Apama queries and a restricted set of bundles. Perhaps the most significant is that each EPL app, which in essence is just an EPL monitor, is completely independent, with the consequence that it is not possible to share event definitions between the apps, which is a common pattern in a standalone correlator. These restrictions are implemented to ensure the smooth and secure operation of EPL apps within Cumulocity IoT.

The editor is based upon the open-source Monaco component used within Visual Studio Code, with a similar level of text editing functionality as there. However, syntax checking is not done until you attempt to save or activate the app. Once you do this, any errors will be underlined and marked in the navigational scroll bar to the right of the editor itself.

Of course, just because an app compiles and activates, doesn’t mean it is doing what you intended. This requires testing, similar to what was mentioned on Day #9. To this end Software AG provides via GitHub the open-source Apama EPL Apps Tools. These tools provide an extension to the PySys testing framework delivered with Apama to allow easy interaction with EPL Apps and the creation of automated tests to ensure your app is working properly. The open-source tool also has links to documentation to help you write these tests.

Documentation for using EPL Apps is available through a button on the toolbar in the editor. Software AG also provides training to help you get started: Cumulocity IoT EPL Apps (CL234C06-75E) (softwareag.com)

The documentation, training, and the samples that are available directly within the EPL Apps UI should give you everything you need to go ahead and create streaming analytics solutions using EPL within Cumulocity IoT. Have fun!

Today’s article was kindly provided by Nicholas Adams from the Apama engineering team.

This is Day #15 of a short series of brief tips, tricks, hints, and reminders of information relating to the Apama Streaming Analytics platform, both from Software AG as well as from the community.
This series of articles will be published Monday-Friday only, with the occasional weekend bonus.