softwareag / apama-analytics-builder-block-sdk

Apama Analytics Builder Block SDK

apama-analytics-builder-block-sdk

This is a Software Development Kit (SDK) for producing blocks for the Apama Analytics Builder Block SDK.

Disclaimer

These tools are provided as-is and without warranty or support. They do not constitute part of the Software AG product suite. Users are free to use, fork and modify them, subject to the license agreement. While Software AG welcomes contributions, we cannot guarantee to include every contribution in the main project.

Licensing

This project is licensed under the Apache 2.0 license - see https://www.apache.org/licenses/LICENSE-2.0

This excludes the Analytics Framework 'CDP' file, which is provided in binary form only for the purpose of testing.

Analytics Builder version

Use the 'main' branch for the current release or switch to the appropriate branch for Long-term support (LTS) / Maintenance releases.

System requirements

This script requires an installation of Python 3.7+ and runs on either Windows or Linux. To build extensions or configure Software AG Designer, a full installation of the latest Apama is required. If you do not already have access, then you can download the Apama Community Edition from Apama Downloads (shortly after the official Software AG release date). If you choose to install Apama, you can skip the manual installation of Python, as it is shipped with Apama.

The apama-builder Docker image from Docker Hub can also be used for building and managing extensions.

Note that Analytics Builder requires your Cumulocity IoT tenant to be subscribed to an 'apama-ctrl' microservice. The 'apama-ctrl-starter' microservice offers only restricted functionality and does not support custom blocks.

Documentation

The guide to writing blocks is available in the doc directory and there is ApamaDoc reference available.

Getting started

From an Apama command prompt:

• Run sample tests (Windows):

set ANALYTICS_BUILDER_SDK=%cd%
cd samples/tests
pysys run

• Run sample tests (Unix):

export ANALYTICS_BUILDER_SDK=`pwd`
cd samples/tests
pysys run

• Package samples as an extension and upload:

analytics_builder build extension --input samples/blocks --cumulocity_url <URL> --username <tenantID>/<username> --password <password> --name sample-blocks --restart

Note: After running the above command, the apama-ctrl microservice will be restarted.

Change Log

See Change Log for changes.

Migration of input and output blocks to the version 2 API

See Migrating input and output blocks to the version 2 API for details on migrating custom input and output blocks to the version 2 API.

apama-analytics-builder-block-sdk's Issues

TestFramework should inject Cumulocity_Utils.mon

This file contains a number of utility functionality (like formatting timestamps):
https://documentation.softwareag.com/onlinehelp/Rohan/Apama/v10-5/apama10-5/ApamaDoc/com/apama/cumulocity/Util.html

as a workaround you can override preInjectBlock but it would be nice if the test framework did this already:

corr.injectEPL(['TimeFormatEvents.mon'], filedir=self.project.APAMA_HOME + "/monitors") corr.injectEPL(['Cumulocity_Utils.mon'], filedir=self.project.APAMA_HOME + "/monitors/cumulocity")

SDK does not work Apama Core Components installation

the Apama Core installation:
https://techcommunity.softwareag.com/en_en/apama-downloads.html

does not include a JRE and the SDK cannot use a Java installation outside of the Apama. The SDK should use the OS JAVA_HOME as a fallback.

Upload without local Apama install

It would be really great to be able to upload onw blocks without the need to install apama locally. Would it be possible to just zip the project and use curl to push it to the tenant

Build shoud skip .git and .github directories

Including them is unnecessary and can lead to build issues. Can be fixed by adding ".git" and ".github" to UNSUPPORTED_FILE_TYPES.

Support block state in $init and $validate

In some cases, it can make sense to populate the state already during the $init or $validation actions if the state can be derived for the parameters and connected inputs and / or will not change afterwards (e.g. converting a human-readable parameter into a format that can be better used in the EPL implementation).

At the moment, one would have to implement this in $process and check if it has already been populated to avoid doing it every time.

Pysys project template for Block tests

As testing blocks requires additional configuration and the use of a different base class, it would be good if Pysys had a template for such a test project.

Documentation link to Apama Python documentation is broken

apama-analytics-builder-block-sdk/doc/035-Testing.md

Line 3 in 15497b5

Blocks can be tested using the PySys testing framework. This is included in the Apama installation, along with extensions for using Apama with PySys. Built on top of the Apama extensions is a framework to test blocks. Refer to the [Apama Python API documentation](https://documentation.softwareag.com/pam/10.15.3/en/webhelp/pydoc/index.html).

Returns a 404.

Test framework should support setting the initial correlator time

AnalyticsBuilderBaseTest has a function timestamp() to set the current correlator time. Using this to set the initial time does not work well if model execution time should be an actual date. Calling self.timestamp(1693388803.554) (which will create a pseudo timestamp event &TIME) will take a very long time as the model needs to process through all the time since time 0.

Apama supports explicitly setting the time with an event like this:
f'&SETTIME({1693388803.000})'

It would be good if the test framework either had a separate function to create a $SETTIME event or if startAnalyticsBuilderCorrelator() had an optional parameter to set the initial time.

Add list of defined categories

Could you pls. add a list of the defined categories in the documentation, e.g.

• @$blockCategory Input
• @$blockCategory Output
• @$blockCategory Logic
• @$blockCategory Calculations
• @$blockCategory Aggregates
• @$blockCategory Flow Manipulation
• @$blockCategory Utilities

Currently only these categories can be used.