Skip to main content

​
Prerequisites

  • Have a Heex CLI
  • Have a API_KEY. Should be accessible in your personnal space on the heex cloud platform. If you already logged-in you don’t need to add the Api-Key in your command line.

​
Usage

SubcommandDescription
getRetrieve implementation details with a given ID.
listRetrieve implementations based on optional filters.
createCreate a new implementation on the cloud.
create-template-fileAdvanced usage: creates a template file for implementation creation configuration.
create-codeVerifies if the implementation id exists in the cloud and generates code for that implementation.
updateUpdate existing implementation for a given id.
deleteDelete an implementaion with a given ID.
unlinkUnlink implementation from a given system.
Usage: 
./heex implementation SUBCOMMAND [--help]

​
How to create a new implementation

2 different ways to create a new implementation on the cloud, both using the command create:
  • Create an implementation only by name and some optional description, using the 2 subcommands:
    • --name: [mandatory] Must be unique on your cloud workspace.
    • --type : [mandatory] Type of the implementation to retrieve details for. (MONITOR or RECORDER).
    • --description: Description for your implementation.
Usage: 
./heex implementation create --api-key <API_KEY> --name "Jane's implementation" --type MONITOR --description "Optional description"
This will create the new implementaion on the Heex Cloud. You can later access this created implementation via the cloud platform and modify it there (i.e add signals).
  • Another way to create an implementation is to use a configuration file that contains all the data you want to generate, if you want to use it:
    • You can generate a template file using the ./heex implementation create-template-file command, and then fill the given file as you need.
    • Once it is filled, use the create subcommand with the --input-file input pointing to the filled file.
Usage: 
./heex implementation create --api-key <API_KEY> --input-file path/to/your/filledConfigFile.json
⚠️ Warning: implementation name or description with special characters If your implementation name or description contains special characters (i.e ’ or space), please use double quotes before and after your names.
For example, for a implementation called Jane’s implementation, provide that as —name “Jane’s implementation”. Note that whichever way you chose to create your implementation, you can add the option --output-file which will save the created data info into a file. You’ll have to provide a filepath with a json extension: /path/to/file.json
  • If you provide --json-output, it will disable all logging (except errors), and your command shall only output the result in a json format. Be aware that it is not compatible with ‘—output-file’ option.

​
How to create implementation code

The create-code command verifies if the implementation id exists in the cloud and generates implementation code for that implementation. Available options:
  • --api-key: Your user api secret key which can be found on the cloud. [required]
  • --implementation-id: ID of the involved implementation. [required]
  • --path-to-sdk: If you don’t run from inside a unzipped sdk package, provide the path to its root.
  • --language: Language of the implementation code, options are [‘python’, ‘cpp’]. [default: python]
  • --name: Name of the implementation file to create. [required]
Usage: 
./heex implementation create-code --api-key <API_KEY> --implementation-id <IMPLEMENTATION_ID> --name <FILE_NAME> --language python
Code will be generated from a basic template. First, we’ll check if the implementation id exists in the cloud. If it does, we’ll generate the code, update the implementation id and save the code in the <SDK_PATH>/samples/code_implementations/<LANGUAGE>/<FILE_NAME>. For C++ implementations, in addition to the implementation file, the following files will be generated:
  • A CMakeLists.txt file in the same directory to configure the build.
  • A buildSample.sh script to compile the code.
After completing your implementation code, simply run the buildSample.sh script to build the executable. To use the implementation(s) please check Run your implementations.

​
How to update an existing implementation

You can update an existing implementation using the update subcommand. This will command allows to add new signals to the existing implementation. Flags implementation-id and signal-id are mandatory. You can provide more than one signal to add to the implementation, check help for more information. Usage: 
./heex implementation update --api-key <API_KEY> --implementation-id <ID> --signal-id <SIGNAL_ID1> --signal-id <SIGNAL_ID2> --signal-id <SIGNAL_ID3>

​
How to get implementation details

You can get the details of a implementation if you provide an implementation-id, see example below: Usage: 
./heex implementation get --implementation-id <IMPLEMENTATION_ID> --api-key <API_KEY> --output-file <OUTPUT-FILE>
This can be useful when you want to get the details of an implementation that you have previously created or if you want to modify a implementation.

​
How to get implementation list

You can get list of all available implementations in a given workspace. Several filters are available to narrow down the results. The flags available to filter the results are:
  • --implementation-id ID of the involved implementation. Multiple can be given: e.g. --implementation-id ID1 --implementation-id ID2.
  • --signal-id Signal IDs to retrieve details for. Multiple can be given: signal-id ID1 signal-id ID1 .
  • --priority Priority of the implementation to retrieve details for. Check the help for available values.
  • --type Type of the implementation to retrieve details for. Check help for available values.
  • --name Name of the implementation to retrieve details for.
  • --output-file The result will be saved into this provided filepath. The output format is json, so please provide a filepath with that format:/path/to/file.json
  • --json-output Disables all logging (except errors), and your command shall only output the result in a json format. It is not compatible with ‘—output-file’ option.
The result can be saved in a json file by using the --output-file flag. If the provided path doesn’t exist, it will be created. See example below where several filters can be used at the same time: Usage: 
./heex implementation list --signal-id <SIGNAL_ID1>  --signal-id <SIGNAL_ID2>  --implementation-id <IMPLEMENTATION_ID1>  --implementation-id <IMPLEMENTATION_ID2> --api-key <API_KEY> --output-file <OUTPUT-FILE>

​
How to delete an implementation

To be able to delete an implementation you need to provide a implementation-id. If the implementation is linked to any system, it is not possible to delete: you need to unlink it from the system(s) first and then try again. Usage: 
./heex implementation delete --api-key <API_KEY> --implementation-id <IMPLEMENTATION_ID>
You can unlink an implementation from a given system using the unlink subcommand. This is useful when you want to remove an implementation from a system before deleting it or when the implementation is not compatible with the system anymore. The available flags are:
  • --api-key: Provide your API_KEY [required].
  • --signal-id: ID of the involved signal [required].
  • --implementation-type: Implementation type (MONITOR or RECORDER) [required].
  • --system-id: ID of the system to unlink the implementation from [required].
Usage: 
./heex implementation unlink --api-key <API_KEY> --signal-id <SIGNAL_ID> --implementation-type <MONITOR|RECORDER> --system-id <SYSTEM_ID>

​
Getting Help

./heex implementation --help
./heex implementation create --help
./heex implementation create-template-file --help
./heex implementation update --help
./heex implementation get --help
./heex implementation list --help
./heex implementation delete --help
./heex implementation unlink --help