Technical Reference

Edge Action Runner Overview

This topic provides detailed information about the Action Runner scripting language that you can use to implement logic in Edge Actions that run on Octave edge devices.

JavaScript Environment

The Action Runner runs the appropriate Actions when their configured triggers are received from the Data Hub.

ECMAScript 5

The environment that executes your code is in strict mode, a restricted subset of JavaScript 5.1. For more information, read the documentation.

With this version you should avoid declaring global variables (use var x = 1; instead of just simply x = 1;). For more information about strict mode, read the Mozilla Developer Network article.

We do not support most features of ECMAScript 6 and we also disallow the use of eval. If you are not familiar with JavaScript, get started in a few minutes with the following resources:

Format

Structure

The Action is a standard ECMAScript 5.1 function, with arity-1:

function ( payload ) {
}

Valid input payload consists of any valid JSON element:

  • JSON Boolean
  • JSON Number
  • JSON String
  • JSON Object
  • JSON Array

Output

Each Action should return a value. If no value is returned, no further work needs to be done. If a value is returned, Action Runner validates it to match the following JSON format:

result = {
     key1 : [ value1, value2, … , valueN],
     key2 : [ … ],
     …
     keyN : [ … ]
}

Each value must be in an array of key/value pairs.

The “keys” specify the target to deliver the payloads. Each key is a URI, comprised of a scheme (), a separator (://), and a path () - i.e. ://. The available key types are:

NameFormat (<destination>://<path>)
Datahub Resourcedh://<resource_value_path>
Virtual Resourcevr://<virtual_resource_name>
Cloud (Immediate)cl://
Cloud (Store and Forward)st://

The “values” are the data to output. Each “value” can be any JSON type (boolean, number, string, object, array).

📘

Note

Events sent from an Edge Action cannot be sent to a named Stream in the Cloud, they will be stored in the :/default Stream of the device.

Each <destination>://<path> entry must be unique.

Errors and Failures

  • If an Action fails validation at compilation (load) time, it cannot be loaded. If it is the sole Action to specify that topic, Octave remove the callback handler for that topic.
  • If an Action fails while executing, an error should be logged, and a value should be written to the Data Hub.
  • If a single output “key” or “value” fails validation, Octave proceeds with the other keys and values and continue to process those which are valid.

Octave Functions

The following JavaScript functions are provided within the environment.

📘

Note

It's recommended that the functions listed below in firmware 3.1.0+ be used where possible.

Functions Available in Firmware 3.1.0+:

Functions Available in all Firmware Versions:

  • Datahub.read(): Performs a read operation on the Data Hub (e.g., to read the value of a resource).
  • Datahub.query(): Performs a query operation which reads the min, max, mean, or standard deviation of a value on the Data Hub.