Level: ADVANCED
Welcome back - we hope you all enjoyed some real chocolates from physical advent calendars over the weekend, assuming your Raspberry Pi advent robot allowed it!
The built-in Apama microservice within Cumulocity IoT (referred from hereon as “apama-ctrl”) normally communicates with the outside world via the Cumulocity IoT core platform and its data model (Measurements, Events, and Alarms). In addition, apama-ctrl can also perform HTTP requests e.g. against other parts of the Cumulocity IoT Core REST API or against other microservices.
Sometimes this is not enough. For example, while Cumulocity IoT supports MQTT that ability is limited (at the time of writing in v10.11). Cumulocity IoT behaves like an MQTT ‘Broker’ but only supports predefined topics with predefined data formats. It cannot connect to another MQTT Broker for example. In such cases, apama-ctrl could be used. Apama has a connectivity plugin for MQTT (mentioned on Day #8) that is actually already installed in apama-ctrl. It only needs to be activated and configured. This short article will explain how.
The mechanism we will be using for this is called an apama-ctrl ‘extension’. These extensions can be built and deployed using Apama Analytics Builder Block SDK (GitHub). This SDK is normally only used to develop custom blocks for Analytics Builder (as described on Day #16) but what it actually does is package an Apama project and upload it into apama-ctrl as an extension. These extensions are merged (ordered by priority) with the Apama project that implements Analytic Builder and EPL Apps functionality. This means that the extension mechanism can also be used to deploy generic EPL code that can then be used in multiple EPL Apps or, in our case, to activate and configure a connectivity plugin.
The Apama installation inside apama-ctrl (as of v10.11) comes with the following connectivity plugins installed:
- HTTP Client (Can already be used through the Generic HTTP Client API without an extension)
- HTTP Server (Unfortunately, microservices can/must only expose a single HTTP port through the Cumulocity IoT microservice framework and apama-ctrl already exposes one, so we can’t expose another)
- Kafka client
- MQTT client
- Universal Messaging client
In addition, the standard String, Classifier, Mapper, Diagnostic, JSON, and Base64 codecs are also installed to handle incoming & outgoing data.
To use any of these connectivity plugins, just configure them as usual in your Apama project in Software AG Designer and build & deploy the project as an extension using Apama Analytics Builder Block SDK. A corresponding folder inside config/connectivity will be created that Apama Analytics Builder Block SDK deploys into the extension. The same mechanism can also be used to deploy custom codecs and connectivity plugins: any Java library (jar) or Linux shared library (so) will be deployed into the extension as well.
There is currently, at the time of writing, a limitation in the Apama Analytics Builder Block SDK in that it does not include properties files and the .settings file in the extension. So you will have to copy these manually.
If something goes wrong with your extension and apama-ctrl can no longer start, it will revert into a safe mode and your extension will be deactivated. You can then either deploy a fixed version or delete the extension from Cumulocity IoT’s file section in the Administration app to solve the issue.
For a general introduction into using the Apama Analytics Builder Block SDK, please check its documentation (v10.11 link): apama-analytics-builder-block-sdk/000-contents.md at rel/10.11.0.x · SoftwareAG/apama-analytics-builder-block-sdk · GitHub.
A final reminder that using the Block SDK in this way is not the purpose for which it was designed, but we know it is has been a get-out-jail-card (Monopoly game reference) for some projects.
Today’s article was kindly provided by Harald Meyer from the Global Competency Centre for IoT team.
This is Day #20 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.