This reference guide provides in-depth information about the Action Runner scripting language used for implementing scripts in Cloud Actions that run logic in the cloud.

JavaScript Environment

Action Runner is built around Octave.js, our server-side JavaScript processing environment. It gives you a library under the Octave namespace. It also executes your code on our servers, ensuring that your code executes safely–both for you and for everyone else on our platform.

Octave.js provides methods for CRUD operations on select Octave domain objects from within Actions. These methods are available in the global namespace Octave.

The Octave namespace provides find() and get() under the sub namespaces: Stream, Event, and Action (see Cloud JavaScript Library for more information). Event also includes aggregate(), findOne(), and findHash() methods.

See Octave.js Reference below for a list of features.

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:

• Learn JavaScript with learnxinyminutes.com
• JavaScript in 14 minutes

Octave.js Reference

Octave.Error

The Octave namespace houses a custom error object, Octave.Error, which is thrown when a fatal error is encountered during the invocation of certain methods. Octave.Error objects have two properties, message and details. message is a string value that represents the general cause of error. details is an array of strings that represent more specific information relating to the cause of error.

Cloud JavaScript APIs

Octave's Cloud JavaScript Library provides an API that can be invoked in both Cloud Action and Task contexts.

See the Cloud JavaScript Library documentation for more information.

📘

Note

All of the APIs in the Cloud JavaScript Library can be invoked in both the Cloud Action and Task contexts, with the exception of Octave.Device.get(), Octave.Device.find(), and Octave.Device.update() which won't work in a Cloud Action context.

Filters

Filters can be used for explicit object matching, as well as members of Stream and Action objects, where they control the types of Event that can enter an Action or Stream.

Note that regular expressions in these filters follow the Java regex format.

Filter Operations

Streams

📘

Note

All Streams functions can "throw" an instance of Octave.Error.

find()

Octave.Stream.find(options)

Parameters

• options: An optional object literal of query options:
• filter: A filter string.
• start: The start index of the search; (default value is 0).
• limit: The maximum response size; (default value 20).
• sort: The string representation of the member key to sort the results over (default value is the creation date).
• order: Specifies the sort order. Can be set to ‘asc’ and ‘desc’ (default value is 'desc').

Returns

An array of JSON representations of the matching Streams.

get()

Octave.Stream.get(streamId)

Parameters

• streamId: the unique ID of the Stream.

Returns

A JSON representation of the matching Stream.

Events

📘

Note

All Events functions can "throw" an instance of Octave.Error.

find()

Octave.Event.find(streamId, options)

Parameters

• streamId: The unique ID of the Stream.
• options: An optional object literal of query options:
• filter: a filter string.
• start: The start index of the search (default value is 0).
• limit: The maximum response size (default value is 20).
• sort: String representation of the member key to sort the results over (default value is the creation date).
• order: Specifies the sort order. Can be set to ‘asc’ and ‘desc’ (default value is 'desc').

Returns

An array of JSON representations of the matching Events.

findone()

Octave.Event.findOne(streamId, options)

Parameters

• streamId: The unique ID of the Stream.
• options: An optional object literal of query options:
• filter: A filter string.
• start: The start index of the search (default value is 0).
• limit: The maximum response size (default value is 20).
• sort: The string representation of the member key to sort the results over (default value is the creation date).
• order: Specifies the sort order. Can be set to ‘asc’ and ‘desc’ (default value is 'desc').

Returns

A JSON representation of a matching Event.

get()

Octave.Event.get(streamId, eventId)

Parameters

• streamId: The unique ID of the Stream that owns the Event.
• eventId: The unique ID of the Event.

Returns

A JSON representation of the matching Event.

Actions

📘

Note

All Actions functions can "throw" an instance of Octave.Error.

find()

Octave.Action.find(options)

Parameters

• options: An optional object literal of query options:
• filter: a filter string.
• start: The start index of the search (default value is 0).
  * limit: The maximum response size (default value is 20).
• sort: The string representation of the member key to sort the results over (default value is creation date).
• order: Specifies the sort order. Can be set to ‘asc’ and ‘desc’ (default value is 'desc').

Returns

An array of JSON representations of the matching Actions.

get()

Octave.Action.get(actionId)

Parameters

• actionId: The unique ID of the Action.

Returns

A JSON representation of the matching Action.

Lodash Functions

The JavaScript utility Lodash (version 3.10.0) is exposed to the Action Runner.

Use to call this library (e.g. ```.includes()```).

For more information, read the documentation.

Manipulating Binary Data

Often times it necessary to manipulate data such as that read from Modbus (e.g., to change endianness). This can be done in an Edge Action or, less commonly, in a Cloud Action, using JavaScript's support for bitwise operators.

For more information about bitwise operator support in JavaScript, see: Bitwise Operators.