​
Prerequisites

  • Have a Heex CLI
  • Have a USER_SECRET_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 trigger details for the given trigger id.
listRetrieve list of triggers based on specified filters.
createCreate a new trigger on the cloud.
updateUpdate an existing trigger on the cloud.
create-template-fileCreates a template file that can be used for creation or update of a trigger.
deleteDelete a trigger with a given ID.
deployDeploy a trigger to a given system or all compatible systems.
linkedRetrieve triggers that are linked to a given system.
candidatesProvides a list of systems where the trigger can be deployed.

Usage:

./heex trigger SUBCOMMAND [--help]

​
How to get trigger details

You can get the details of a trigger if you provide a trigger-id, see example below:

Usage:

./heex trigger get --trigger-id <TRIGGER_ID> --api-key <USER_SECRET_KEY> --output-file <OUTPUT-FILE>

This can be useful when you want to get the details of a trigger that you have previously created or if you want to modify a trigger.

​
How to get trigger list

You can get list of all available triggers in a given workspace. Several filters are available to narrow down the results. The flags available to filter the results are:

  • --system-id ID of the involved system.
  • --trigger-id ID of the involved trigger. Multiple can be given: e.g. --trigger-id 1 --trigger-id 2 --trigger-id 3.
  • --trigger-name Name of the trigger to retrieve details for. Multiple can be given: --trigger-name name1 --trigger-name name2.
  • --priority Priority of the trigger to retrieve details for. Multiple can be given: --priority 1 --priority 2.
  • --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

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 trigger list --system-id <SYSTEM_ID1> --system-id <SYSTEM_ID2> --trigger-id <TRIGGER_ID1> --trigger-id <TRIGGER_ID2> --api-key <USER_SECRET_KEY> --output-file <OUTPUT-FILE>

​
How to create triggers

There are 2 possible ways to create a new trigger, either by providing a json file with the trigger details or by providing the details directly in the command line. When using a file you can create multiple triggers, otherwise you can create only one trigger at the time.

The flags that are available to achieve this command are the following:

  • --api-key: Provide your USER_SECRET_KEY.
  • --name: Trigger name to create [required if not using a file].
  • --description: Description of the trigger [optional].
  • --input-file: Full path to the input file to use, it has to be a .json file, example : /path/to/input.json

To create a trigger by providing options, see example below:
Usage:

./heex trigger create --api-key <USER_SECRET_KEY> --name <TRIGGER_NAME> --description <TRIGGER_DESCRIPTION>

Create triggers using a json file
If you want to create a trigger where you can specify conditions then you should use json file with the trigger details. You can use command below to generate a template file. If no --folder-path is provided, the template will be saved in the current directory.

Usage:

./heex trigger create-template-file --folder-path <FOLDER_PATH>

Once the template file is generated, you can fill the details and use it as input file. See an example of file with monitoring_signal_condition and recording_signal_condition below:

{
  "labels": [
    {
      "key": "TestKey",
      "value": "TestValue"
    }
  ],
  "monitoring_signal_conditions": [
    {
      "value": {
        "string": "test"
      },
      "signal_id": "si-xxxxxxxxxxxx",
      "operator": "CONTAIN",
      "unit": "METER"
    }
  ],
  "recording_signal_conditions": [
    {
      "signal_id": "si-xxxxxxxxxxxx"
    }
  ],
  "name": "TriggerTestWithFile",
  "priority": 1,
  "description": "TriggerTestWithFile"
}

Usage:

./heex trigger create --api-key <USER_SECRET_KEY> --input-file create_trigger_template.json

Only name is mandatory. Other fields are optional and can be removed from the template file if not needed. Note that for the creation to work properly you need to remove the fields that are not necessary for your trigger. If you need help to fill the template file, you can check the Trigger Options Help for more information about possible values of several fields.

​
How to update a trigger

You can update a trigger by using a json file. Flags to update a trigger are --input-file and --trigger-id which are both required. You can generate a template file using the same command as for the creation:

Usage:

./heex trigger create-template-file --folder-path <FOLDER_PATH>

Once the template file is generated, you can fill the details and use it as input file:

Usage:

./heex trigger update --api-key <USER_SECRET_KEY> --trigger-id <TRIGGER_ID> --input-file create_trigger_template.json

​
How to deploy a trigger

You can deploy a trigger to a given system or to all systems that are compatible with it. A trigger is compatible with a system if all datasources used for the trigger are also linked to the system.

The available flags are:

  • --api-key: Provide your USER_SECRET_KEY [required].
  • --trigger-id: ID of the trigger to deploy [required].
  • --system-id: ID of the system to deploy the trigger to [mutually exclusive with --to-all-systems].
  • --to-all-systems: Deploy to all compatible systems [mutually exclusive with --system-id].

Usage:

# Deploy to one system
./heex trigger deploy --api-key <USER_SECRET_KEY> --trigger-id <TRIGGER_ID> --system-id <SYSTEM_ID>

# Deploy to all compatible systems
./heex trigger deploy --api-key <USER_SECRET_KEY> --trigger-id <TRIGGER_ID> --to-all-systems

​
How to get triggers linked to a system

This command returns the list of triggers that are currently linked to a given system.

The available flags are:

  • --api-key: Provide your USER_SECRET_KEY [required].
  • --system-id: ID of the system to retrieve linked triggers for [required].
  • --output-file: Filepath where the result will be saved (JSON format).
  • --details: If specified, shows detailed information (ID, status, etc.). If not, only trigger IDs are displayed.

Usage:

./heex trigger linked --api-key <USER_SECRET_KEY> --system-id <SYSTEM_ID> --output-file <OUTPUT-FILE> --details

If --details is not provided, only the list of trigger IDs is shown.

​
How to get candidate systems for trigger deployment

This command provides a list of systems where a given trigger can be deployed. It is useful to verify compatibility before deploying.

The available flags are:

  • --api-key: Provide your USER_SECRET_KEY [required].
  • --trigger-id: ID of the trigger to check for compatible systems [required].
  • --output-file: Filepath where the result will be saved (JSON format recommended).

Usage:

./heex trigger candidates --api-key <USER_SECRET_KEY> --trigger-id <TRIGGER_ID> --output-file <OUTPUT-FILE>

​
How to delete a trigger

To be able to delete a trigger you need to provide a trigger-id. If the trigger 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 trigger delete --api-key <USER_SECRET_KEY> --trigger-id <TRIGGER_ID>

​
Getting Help

./heex trigger --help
./heex trigger get --help
./heex trigger list --help
./heex trigger update --help
./heex trigger create --help
./heex trigger create-template-file --help
./heex trigger delete --help
./heex trigger deploy --help
./heex trigger linked --help
./heex trigger candidates --help