Apama Analytics Builder block SDK for 10.16.0.1

README.md

@@ -14,7 +14,7 @@ This excludes the Analytics Framework 'CDP' file, which is provided in binary fo
 
 ## Analytics Builder version
 
-This version of the SDK supports Analytics Builder 10.15.0.  To make use of this, you will require an installation of Apama 10.15.0. If you do not already have access, then you can download the 'community' edition from [Apama Downloads](https://apamacommunity.com/downloads) (shortly after the official Software AG release date).
+This version of the SDK supports Analytics Builder 10.16.0.  To make use of this, you will require an installation of Apama 10.15.1. If you do not already have access, then you can download the 'community' edition from [Apama Downloads](https://apamacommunity.com/downloads) (shortly after the official Software AG release date).
 
 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.
 

bundles/AnalyticsBuilder.bnd

@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <bundle name="Analytics Builder" type="monitorscript" singleton="true">
 	<version>
-		<id>10.15.0.2</id>
+		<id>10.16.0.1</id>
 		<date>2019-06-07</date>
 		<author>Software AG</author>
 		<comments/>

bundles/CumulocityHelper.bnd

@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <bundle name="Cumulocity Block Helpers" type="monitorscript" singleton="true">
 	<version>
-		<id>10.15.0.2</id>
+		<id>10.16.0.1</id>
 		<date>2020-06-29</date>
 		<author>Software AG</author>
 		<comments/>

doc/005-Intro.md

@@ -6,7 +6,7 @@ Analytic models run in the Apama correlator, and are managed by the Analytics Bu
 
 Blocks can be tested using the PySys test framework that is included in an Apama installation. In order to develop, test and package blocks, you will need a full installation of Apama.
 
-Blocks are implemented in Apama's Event Processing Language (EPL). This guide assumes a working knowledge of EPL. Refer to the [Apama documentation on developing EPL applications](https://documentation.softwareag.com/pam/10.15.0/en/webhelp/pam-webhelp/index.html#page/pam-webhelp%2Fco-DevApaAppInEpl_how_this_book_is_organized.html) and the [API Reference for EPL (ApamaDoc)](https://documentation.softwareag.com/pam/10.15.0/en/webhelp/ApamaDoc/index.html). This guide also assumes a working knowledge of the Analytics Builder data model. Refer to the [Apama Analytics Builder documentation](https://documentation.softwareag.com/pab/10.15.0/en/webhelp/pab-webhelp/index.html#page/pab-webhelp%2Fto-AnaBui_getting_started_with_apama_analytics_builder.html).
+Blocks are implemented in Apama's Event Processing Language (EPL). This guide assumes a working knowledge of EPL. Refer to the [Apama documentation on developing EPL applications](https://documentation.softwareag.com/pam/10.15.1/en/webhelp/pam-webhelp/index.html#page/pam-webhelp%2Fco-DevApaAppInEpl_how_this_book_is_organized.html) and the [API Reference for EPL (ApamaDoc)](https://documentation.softwareag.com/pam/10.15.1/en/webhelp/ApamaDoc/index.html). This guide also assumes a working knowledge of the Analytics Builder data model. Refer to the [Apama Analytics Builder documentation](https://documentation.softwareag.com/pab/10.16.0/en/webhelp/pab-webhelp/index.html#page/pab-webhelp%2Fto-AnaBui_getting_started_with_apama_analytics_builder.html).
 
 The Analytics Builder block SDK has branches in a GitHub repository. You need to download the appropriate release of the block SDK based on the version of the Cumulocity IoT tenant you are using. Refer to the [Releases](https://github.com/SoftwareAG/apama-analytics-builder-block-sdk/releases) page of the block SDK. The version of the block SDK should be compatible with the version of the Cumulocity IoT tenant.
 

doc/010-BasicBlocks.md

@@ -21,6 +21,9 @@ package apamax.sampleblock;
 using apama.analyticsbuilder.BlockBase;
 using apama.analyticsbuilder.Activation;
 
+/**
+ * @$blockCategory Calculations
+ */
 event Offset {
     BlockBase $base;
     action $process(Activation $activation, float $input_value) {
@@ -29,7 +32,10 @@ event Offset {
     action<Activation, float> $setOutput_output;
 }
 ```
-**Note:** A block must be defined inside a package.
+> **Hints:**
+> - A block must be defined inside a package.
+> - Setting the `@$blockCategory` ApamaDoc tag is mandatory.  For more information, see [Naming and Documenting Blocks](020-NamingAndDoc.md).
+
 
 This block simply adds 100 to every input value. The `$process` action has parameters for the inputs, and the output is sent by calling the `$setOutput_output` action field. The framework takes care of creating an instance of the block when it is required for a model, initializing the `$base` and `$setOutput_output` fields and calling the `$process` action when the block receives input.
 

doc/020-NamingAndDoc.md

@@ -39,7 +39,7 @@ If a field of the block or a parameter of the `$process` method has a `$` prefix
 
 The block's name and description are also provided in ApamaDoc comments, before the event definition of the block. In the block's ApamaDoc comment, the supported extended tags include:
 
-* `@$blockCategory <Category>` - identifies the category in the model editor's palette in which the block should appear. See "Allowed categories" for more information.
+* `@$blockCategory <Category>` - (***required***) identifies the category in the model editor's palette in which the block should appear. See [Allowed categories](020-NamingAndDoc.md#Allowed-categories) for more information.
 * `@$derivedName` - provides a name which can include a parameter value by using `${parameterId}` or `$parameterId`. Use `$$` for a literal dollar sign.
 * `@$titleIsDerived` - if set and true, use the derived name in the block parameters dialog as well; typically only set for input/output blocks.
 

doc/030-BuildingExtensions.md

@@ -2,7 +2,7 @@
 
 Once a block is written in EPL, it can be packaged into an "extension". Extensions are **.zip** files that can be used to add blocks to the Analytics Builder runtime. Analytics Builder is deployed within Cumulocity IoT, and extensions are stored in the inventory. The extensions are only read when the Apama-ctrl microservice inside Cumulocity IoT is started, so the service must be restarted to make use of a new block. Restarting the microservice will lose state in any running models or custom EPL applications running in that tenant. This SDK provides a command line utility called `analytics_builder` which is available in the root directory of the SDK. This can be used to build an extension or list an extension or manage an extension in a Cumulocity IoT installation. You must navigate out of the model editor to the model manager and back to the editor to expose the new blocks after uploading an extension.
 
-Most of the `analytics_builder` commands use a `--input` argument which specifies the path to a directory. All **.mon** files found under that directory will be included, and message files matching **\*-messages.json** or named **messages.json** will be used for the runtime messages. 
+Most of the `analytics_builder` commands use a `--input` argument which specifies the path to a directory. All files except **.log**, **.classpath**, **.dependencies**, **.project**, **.deploy**, **.launch**, **.out**, and **.o** found under that directory will be included, and message files matching **\*-messages.json** or named **messages.json** will be used for the runtime messages.
 
 The `analytics_builder` script is run from an Apama command prompt (on Windows, run **Apama Command Prompt** from the Start Menu group of your Apama installation; on Linux, source the `apama_env` script). **Note:** You must place the script in a directory that does not have any spaces in its full path. 
 

doc/035-Testing.md

@@ -1,6 +1,6 @@
 # Testing blocks
 
-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.0/en/webhelp/pydoc/index.html).
+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.1/en/webhelp/pydoc/index.html).
 
 The samples include tests. The `pysystestproject.xml` configuration relies on the environment variable `ANALYTICS_BUILDER_SDK` being set to the location of the block SDK using an absolute path. PySys tests should contain a `run.py` with a class that extends `apama.analyticsbuilder.basetest:AnalyticsBuilderBaseTest`. In the `execute` method of the test, start a correlator with the `self.startAnalyticsBuilderCorrelator()` method. This starts a correlator, injects the Analytics Builder framework into it, and returns a `CorrelatorHelper` object. Provide a `blockSourceDir` parameter with the path to the source of the blocks, typically within the project tree (use `self.project.SOURCE` from the supplied `pysysproject.xml` file). Then, create a model to test the block with the `self.createTestModel('<blockUnderTest>')`  This results in a model being activated in the correlator with an input and output connected to every input and output of the block, and an identifier of the model is returned. The block can be exercised by sending events created by the `self.inputEvent` method, for a given block input identifier.
 
@@ -13,7 +13,7 @@ Both `createTestModel` and `inputEvent` take an optional argument: `id` - an ide
 * `parameters` (optional) - dictionary of block parameter identifier to value. If there are multiple blocks, each block is prefixed with the block index.
 * `id` (optional) - identifier of the model
 * `corr` (optional) - correlator to use; defaults to using the last correlator started by `startAnalyticsBuilderCorrelator`.
-* `inputs` (optional) - a map of the types of inputs, from input identifier to the type of the input.  If an input identifier is not specified, the input defaults to the 'float' type. If the value for the identifier is set to 'None; or an empty string, that input is not connected
+* `inputs` (optional) - a dictionary that maps the input names to their types.  For example `{ "input1" : "string", "input2" : "integer" }`. If an input identifier is not specified, the input defaults to the `float` type. If the value for the identifier is set to `None` or an empty string, that input is not connected.
 * `wiring` (optional unless testing multiple blocks) - list of strings containing source block index, output port identifier, target block index, input port identifier separated by colons - e.g. `['0:timeWindow:1:window']`
 
 
@@ -24,7 +24,11 @@ The following methods can be used to check the output of the block is as expecte
 * `allOutputFromBlock` returns a list of all of the outputs from a block, a list of dictionaries where each dictionary has `outputId`, `partitionId`, `time`, `properties` and `value` entries.
 
 
-Note that the correlator started by `startAnalyticsBuilderCorrelator` is externally clocked. Each event is treated as if it has occurred at the time of the most recent timestamp event. The models will execute 0.1 seconds behind the input timestamps - so a model will only process an input if a timestamp is sent at least 0.1 seconds after the previous timestamp. If multiple values for the same input are received at the same correlator time, it is undefined which will be processed.  Different values for different inputs can be provided and will evaluate once. The timestamps in the model output will be use the same time as the timestamps on the inputs. Use the `timestamp` method to generate a time pseudo-event.
+Note that the correlator started by `startAnalyticsBuilderCorrelator` is externally clocked, meaning that the correlator's time increments only when a timestamp event is received. Consequently, events arriving between timestamp events are assigned the same time, that is, the time of the last timestamp.
+
+After a timestamp is received, subsequent events are held until the next timestamp event that has a time at least 0.1s greater. All of the events are then processed together. If a value for a particular input is received while an event for that input is already waiting, only one of the events will be retained and then sent to the model. The other value will be discarded. (Whether this is the new value or the existing, waiting value is undefined.)
+
+The `timestamp` method can be used to generate a time pseudo-event when testing. If events modifying multiple inputs are sent to the model between timestamps (and those timestamps are at least 0.1 seconds apart), the new values will be received by the model simultaneously and evaluated once. For an example of this, see the **GroupStatistics_Bounded** test sample in the in the **samples/tests** directory.
 
 For example, a simple test is: