The apama_project tool

Creating and managing an Apama project

The apama_project tool can be used to create a directory for your Apama project, and add EPL and connectivity bundles to it.

It lets you perform the following actions:

create an Apama project,
list all supported bundles that can be added to a project,
list all bundles/instances that have already been added to a project,
add connectivity, adapter and EPL bundles and their instances to a project,
remove bundles/instances from a project,
configure which subdirectories within the project contain Apama application files.

The executable for this tool is located in the Apama/bin directory.

The project directory created by apama_project tool is the input engine_deploy requires to generate a deployment directory that can be passed to the correlator to run the application.

Synopsis

To use this tool, run the following command:

apama_project command [options]

When you run this command with the help (or --help, -help or –h) option, the usage message for this command is shown. For example:

To display help for all commands:
```
apama_project help
```
To display help for a specific command:
```
apama_project command help
```

Description

You can only specify one command at a time.

Apart from the command for creating a project, all other commands require you to run the tool from the project directory.

The apama_project tool takes the following commands and options:

Command	Option	Description
`create`	`projectname`	Creates a new project directory with the specified name in the current directory. If the project name is to consist of more than one word, you have to enclose it in quotes. Note: We recommend committing your project into a version control system, so that changes are recorded and you can compare or revert changes across versions if needed.
`list bundles`	(none)	Lists all connectivity, adapter and EPL bundles that are available for adding to the project. Also lists the bundles with instance information that are already present in the project. Some bundles support adding several instances to the same project if desired. For example, you can add separate HTTP Client connectivity bundle instances to talk to different servers. Other bundles support adding only one instance. Such “singleton” bundles, once added to the project, will no longer show up in the list of bundles that can be added. Index numbers are shown for the bundles which can still be added. They can be used as shortcuts instead of typing the full name. Note that the index numbers are subject to change; they differ each time a bundle has been added. So if you want to use the number shortcut, list the bundles once more in order to find the correct number.
`add bundle`	`bundlename [--instance instancename]`	Adds the specified bundle to the project (created using the `apama_project` tool). The `bundlename` can be a display name that was displayed by the `list bundles` command or the absolute path of a `.bnd` file. If the name consists of more than one word, you have to enclose it in quotes. Instead of specifying a bundle name, you can also specify the corresponding index number that has been output with the `list bundles` command. For bundles supporting multiple bundle instances, you can optionally specify a user-defined instance name using `--instance instancename`. This is useful for indicating the logical name or purpose of the service or server being connected to. For some bundles, the provided instance name may be used in EPL code. Once added, the instance cannot be renamed, though it is possible to delete and re-add it with a different name. If a user-defined instance is not specified, the default instance name is used. Duplicate instance names are not allowed for the project, even if the instances are of different bundles. You can only add bundles from the standard EPL and connectivity catalogs. Adding bundles from the Capital Markets Foundation, Capital Markets Adapters, or user-defined bundle catalogs is not supported.
	`bundlename bundlename...`	Adds multiple bundles to the project (created using the `apama_project` tool). The `bundlename` can be a display name that was displayed by the `list bundles` command, an absolute path to a `.bnd` file from `APAMA_HOME`, or a relative path to a custom (non-product) `.bnd` bundle file located somewhere near the project directory. If the name consists of more than one word, you have to enclose it in quotes. Note: When adding multiple bundles, it is not permitted to specify index numbers or the `--instance` argument.
`remove bundle`	`bundlename` \| `instancename`	Removes the specified bundle from the project. Either specify an `instancename` to remove a specific instance or specify a `bundlename` to remove all instances associated with the specified bundle display name or `.bnd` filename. CAUTION: All associated instance files in your project directory will be deleted from disk. So check carefully and take a backup of your project if you are in doubt whether you really want to delete it.
`config`	`src=subdir1,subdir2,...`	Sets a configuration option for this project. At present the only supported configuration option is `src=`, which provides a comma-separated list of project subdirectories which will be recursively searched for project source files by `engine_deploy` and related tools. The default configuration is `.` which means all files and subdirectories of the project directory will be walked. You may wish to change this if your top-level directory if very large, or if it contains files which are not part of the application you’re deploying such as testcase `.mon` files.
`config`	(none)	Prints the current configuration options for this project. At present the only supported configuration option is `src=` (see above).

Examples

The following examples show the different ways in which the apama_project tool can be started.

Note: Keep in mind that you have to change to the project directory if you want to run the commands for listing, adding or removing bundles.

Create an Apama project that is named “MyApamaProject” in the current directory:
```
apama_project create MyApamaProject
```
List all connectivity and EPL bundles in APAMA_HOME that can be added to the current Apama project:
```
apama_project list bundles
```
Add a bundle to the current Apama project, with a user-defined instance name:
```
apama_project add bundle "HTTP Client" --instance "MyHTTP"
```
Add a bundle to the current Apama project using the index number:
```
apama_project add bundle 34
```

Add a non-product bundle to the current Apama project using a relative path:

apama_project add bundle ../apama-analytics-builder-block-sdk/AnalyticsBuilder.bnd

Remove a bundle from the current Apama project, including all of its instances:
```
apama_project remove bundle "HTTP Client"
```

About project bundles

Bundles are named collections that group the Apama objects that are necessary for different types of applications. There are two kinds:

Standard (EPL) bundles. This bundle contains standard EPL bundles supplied with the product. These bundles contain monitors and event definitions that are specific to the type of application you are building. For example, applications that use the JSON EPL plug-in need the JSON bundle.
Connectivity bundles. This bundle contains the connectivity bundles supplied with the product, each of which contains connectivity configuration files (YAML and properties files), and sometimes also references to supporting EPL monitors.
User bundles. The user bundles are user-defined bundles that are not packaged with the product, for example user-defined connectivity plug-ins. If you want to add a user bundle, copy the user bundle file to the catalogs\bundles directory in your Apama work directory.

Many bundles contain only EPL or Java files. Adding these bundles means that references to the bundle files will be added to the project build path, but does not involve copying any files into the project. However, when you add a connectivity bundle that contains customizable files such as .evt or configuration files, apama_project physically copies these files into the project, in addition to the changes made to the build path.

When adding any connectivity bundle, the standard-codecs.yaml file is included by default, which adds the standard codecs defined by Apama; see Codec connectivity plug-ins for more information. Also, a .yaml and a .properties file is copied into the project. References to bundled EPL files are also added

If you add more than one instance of a particular connectivity bundle or an adapter bundle to the project, apama_project creates separate copies of these files for each instance (except for bundles where it only makes sense to have one copy of the instance files per project). You can change and customize the bundle instance files in any manner. It is possible to add multiple instances of such bundles to a given project to allow different customization of the same instance files, for example if your application needs to run with two instances of a particular adapter, each connected to a different data provider.

Connectivity bundles

Apama supports the following connectivity bundles:

User Connectivity. Select an instance of User Connectivity if you want to make use of any user-defined connectivity plug-ins. For more information, see Using connectivity plug-ins.
MQTT. Apama supports MQTT, which is a publish/subscribe-based “lightweight” message protocol designed for communication between constrained devices, for example, devices with limited network bandwidth or unreliable networks. Select an instance of MQTT if you want to make use of the MQTT connectivity plug-in. For more information, see Adding the MQTT connectivity plug-in to a project.
HTTP Server. The HTTP server is a transport for use in connectivity plug-ins which external services can connect to over HTTP/REST. Select an instance of HTTP Server if you want to make use of the HTTP server connectivity plug-in. For more information, see Adding the HTTP server connectivity plug-in to a project.
HTTP Client. The HTTP client is a transport for use in connectivity plug-ins which can connect to external services over HTTP/REST, perform requests on them and return the response as an event. Select an instance of HTTP Client if you want to make use of the HTTP client connectivity plug-in. For more information, see Adding the HTTP client connectivity plug-in to a project.
Cumulocity. There are several bundles used for communication with IoT devices via the Cumulocity platform. For further information, see Adding the Cumulocity connectivity plug-in to a project.

Adding the Cumulocity connectivity plug-in to a project

In Apama applications, you can configure and use the Cumulocity connectivity plug-in provided with Apama.

To use this plug-in, add one of its bundles to your project as as described above. You must select (only) one of the following bundles:

Cumulocity Notifications 2.0

Info

Cumulocity Notifications 2.0 is currently only available as a private preview. Request access from Cumulocity Operations.

The following files are created:
- CumulocityIoTREST.properties
  
  Edit this file to configure the connection details to your Cumulocity tenant.
- CumulocityNotifications2.properties
  
  Edit this file to configure receiving real-time notifications.
Cumulocity REST Support

Info

Only add this bundle if you are not receiving notifications in your project and just want to send to or query the Cumulocity Platform. If you want to receive notifications, add one of the other bundles instead.

The following file is created:
- CumulocityIoTREST.properties
  
  Edit this file to configure the connection details to your Cumulocity tenant.
Cumulocity Client

Info

The Cumulocity Client bundle connects using the deprecated long-polling mechanism. It is recommended that you use the Cumulocity Notifications 2.0 bundle instead.

The following files are created:
- CumulocityIoT.properties
  
  Edit this file to configure the Cumulocity connectivity plug-in.
- CumulocityIoT.yaml
  
  Info
  
  It is strongly recommended that you do not change the CumulocityIoT.yaml file. You should always set the properties in the CumulocityIoT.properties configuration file, which defines the substitution variables to be used in the CumulocityIoT.yaml file.

For further information, see The Cumulocity transport connectivity plug-in.

Adding the MQTT connectivity plug-in to a project

To use this plug-in, add its bundle to your project as as described above. The following files are copied to the project:

MQTT_bundle_instance.properties
MQTT_bundle_instance.yaml

Edit these are needed to configure the MQTT connectivity plug-in. For more information, see The MQTT Transport Connectivity Plug-in.

Adding the HTTP server connectivity plug-in to a project

To use this plug-in, add its bundle to your project as as described above. The following files are copied to the project:

HTTP_Server_bundle_instance.properties
HTTP_Server_bundle_instance.yaml
swagger_HTTP_Server_bundle_instance.json

Edit HTTP_Server_bundle_instance.properties to configure the HTTP server port, that is, the port on which the server is listening for HTTP requests.

Edit HTTP_Server_bundle_instance.yaml to configure the HTTP server connectivity plug-in. For more information, see The HTTP Server Transport Connectivity Plug-in.

Edit swagger_HTTP_Server_bundle_instance.json if you want to add more static files. For more information, see OpenAPI definitions and Serving static files.

Adding the HTTP client connectivity plug-in to a project

To use this plug-in, add one of its bundles to your project as as described above. There are several bundles to choose from:

one that uses application-specific event definitions, transports and mapping configurations, and
one that uses generic Apama event definitions and a chain configuration to invoke HTTP services with JSON payloads. This option can be added only once and can be used to invoke multiple HTTP services.

The following files are copied to the project:

HTTP_Client_bundle_instance.properties This` file contains properties for configuring the HTTP client transport.
HTTP_Client_bundle_instance.yaml

If you have selected the “generic” option, the above files are not created. This works without any configuration. All configuration options and mappings are provided at runtime through the EPL application.

If you have not selected the “generic” option, edit the HTTP_Client_bundle_instance.yaml file to specify more advanced configurations, such as customizing the way HTTP messages are mapped to Apama events, using codecs for converting the message payload, or configuring the HTTP client transport. For more information, see The HTTP Client Transport Connectivity Plug-in.

The HTTP client adds a reference to com.apama.util.AnyExtractor which is useful for easily extracting data from an any type; see the API reference for EPL (ApamaDoc) for more details.