Apama Analytics Builder block SDK for 10.11.0.1

CHANGELOG.md

@@ -4,3 +4,6 @@
 * The version 2 API for writing input and output blocks is available.
 * The version 1 API for writing input and output blocks is deprecated. Existing blocks will need to be migrated. See [Migrating input and output blocks to the version 2 API](doc/150-MigrateInputOutputBlocks.md) for more details.
 
+## 10.11.0.0
+* You can now build an extension by skipping uninteresting folders from the build. See [Building a block into an extension](doc/030-BuildingExtensions.md) for more details.
+* It is now possible to list the extensions that are uploaded to a Cumulocity IoT instance. See [Building a block into an extension](doc/030-BuildingExtensions.md) for more details.

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.10.0.  To make use of this, you will require an installation of Apama 10.7.2. If you do not already have access, then you can download the 'community' edition from <http://www.apamacommunity.com/downloads/> (shortly after the official Software AG release date).
+This version of the SDK supports Analytics Builder 10.11.0.  To make use of this, you will require an installation of Apama 10.11.0. If you do not already have access, then you can download the 'community' edition from <https://www.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.
 

analytics_builder

@@ -8,7 +8,7 @@ import argparse, tempfile, traceback
 
 sys.path.append(os.fspath(pathlib.Path(__file__).parent.joinpath('scripts')))
 
-import blockMetadataGenerator, buildExtension, configure_designer, jsonHelper, uploadExtension
+import blockMetadataGenerator, buildExtension, configure_designer, jsonHelper, uploadExtension,listExtensions
 
 class Command(object):
 	def __init__(self, name, help, sub_commands=None, required=True):
@@ -57,6 +57,10 @@ def main():
 					   'Upload a zip file of the Analytics Builder extension and optionally upload it to the Cumulocity inventory. ' +
 					   'You can also delete already uploaded extensions. After uploading or deleting an extension, ' +
 					   'you have to restart the Apama service for this to take effect.')
+		]),
+		Command('list', 'list all extensions', [
+			SubCommand('extensions', 'list extensions', listExtensions.add_arguments, listExtensions.run, False,
+					   'Lists all extensions installed on the given tenant. ')
 		])
 	]
 

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.10.0.3</id>
+		<id>10.11.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.10.0.3</id>
+		<id>10.11.0.1</id>
 		<date>2020-06-29</date>
 		<author>Software AG</author>
 		<comments/>

doc/005-Intro.md

@@ -6,9 +6,9 @@ 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](http://www.apamacommunity.com/documents/10.7.2.0/apama_10.7.2.0_webhelp/apama-webhelp/#page/apama-webhelp%2Fco-DevApaAppInEpl_how_this_book_is_organized.html) and the [API Reference for EPL (ApamaDoc)](http://www.apamacommunity.com/documents/10.7.2.0/apama_10.7.2.0_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/onlinehelp/Rohan/Analytics_Builder/pab10-10-0/apama-pab-webhelp/index.html#page/apamaanalyticsbuilder-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/apama/v10-11/apama10-11/apama-webhelp/index.html#page/apama-webhelp%2Fco-DevApaAppInEpl_how_this_book_is_organized.html) and the [API Reference for EPL (ApamaDoc)](https://documentation.softwareag.com/apama/v10-11/apama10-11/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/apama/Analytics_Builder/pab10-11-0/apama-pab-webhelp/index.html#page/apamaanalyticsbuilder-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. 
+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.
 
 Blocks can range from very simple stateless functions to more complex logic. Blocks can make use of:
 

doc/030-BuildingExtensions.md

@@ -1,6 +1,6 @@
 # Building a block into an extension
 
-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 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 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.
+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. 
 
@@ -24,12 +24,27 @@ The `analytics_builder` script takes a two-word command, followed by any argumen
   analytics_builder build extension --input samples/blocks --cumulocity_url https://demo.cumulocity.com/ --username tenantID/user --password pass
   ```
 
+* `build extension --cumulocity_url <url> --username <user> --password <password> --folderToSkip <folder_name>`
+
+  Build and upload an extension to a Cumulocity IoT instance by skipping uninteresting folders from the build. For example:
+
+  ```bash
+  analytics_builder build extension --input samples/blocks --cumulocity_url https://demo.cumulocity.com/ --username tenantID/user --password pass --folderToSkip temp --folderToSkip temp1
+  ```
+
 * `upload extension --cumulocity_url <url> --username <user> --password <password> --input <path to zip file>`
 
   Upload an extension to a Cumulocity IoT instance.  Note that the 'apama-ctrl-starter' version of Apama in Cumulocity IoT does not support extensions and thus you cannot use it for custom blocks.
-  Ask your support contact to upgrade to a fully-featured version of apama-ctrl.
+  Ask your support contact to upgrade to a fully-featured version of the Apama-ctrl microservice.
+
+* `list extensions --cumulocity_url <url> --username <user> --password <password> `
 
+  List extensions that are uploaded to a Cumulocity IoT instance. For example:
 
+  ```bash
+  analytics_builder list extensions --cumulocity_url https://demo.cumulocity.com/ --username tenantID/user --password pass
+  ```
+
 * `build metadata --output <json file>`
 
   Build JSON metadata only. This can be useful for reviewing what is extracted from the block and visible in the model editor. For example:
@@ -53,9 +68,9 @@ See the `analytics_builder --help` output for full details of the options.
 For `build extension` and `upload extension`:
 
 * The `--username` argument can also take the tenant identifier along with user name in the format `tenantID/username`.  The user must have the 'Inventory - CREATE' permission to upload an extension.
-* Specify `--restart` to request a restart of the apama-ctrl service.  The user must have the 'CEP management - ADMIN' permission to request a restart.
+* Specify `--restart` to request a restart of the Apama-ctrl microservice.  The user must have the 'CEP management - ADMIN' permission to request a restart.
 * Specify `--delete` and `--name <base name of extension>` to delete a previously uploaded extension.
-* Specify `--ignoreVersion` to not check whether the script and apama-ctrl service are of the same version.
+* Specify `--ignoreVersion` to not check whether the script and Apama-ctrl microservice are of the same version.
 
 
 **Note:** If you wish to use the samples provided in the **samples** directory as the starting point for your own blocks, it is strongly recommended that you:

doc/035-Testing.md

@@ -1,11 +1,11 @@
 # 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](http://www.apamacommunity.com/documents/10.7.2.0/apama_10.10.0.0_webhelp/pydoc/).
+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/apama/v10-11/apama10-11/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. 
+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.
 
 
-Both `createTestModel` and `inputEvent` take an optional argument: `id` - an identifier of the model. If an identifier is not specified, `createModel` will use the identifiers `model_0` and upwards, and `inputEvent` will use `model_0` (that is, the first created model). 
+Both `createTestModel` and `inputEvent` take an optional argument: `id` - an identifier of the model. If an identifier is not specified, `createModel` will use the identifiers `model_0` and upwards, and `inputEvent` will use `model_0` (that is, the first created model).
 
 `createTestModel` takes these arguments:
 
@@ -14,7 +14,7 @@ Both `createTestModel` and `inputEvent` take an optional argument: `id` - an ide
 * `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
-* `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']` 
+* `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']`
 
 
 The following methods can be used to check the output of the block is as expected: