Bolt Data Connect – Scripting

Docs: Writing Formulas

Mon, 01 Jan 0001 00:00:00 +0000

Edge processing takes sensor data, aggregates it, and computes all the Calculations and Alerts all according to your Thing Type Specifications.

The following section describes the syntax for writing these functions. The base syntax for all these formulas is JavaScript (specifically Node.js).

Function Basics

Let’s assume our Example IoT Connected Asset produces a message which looks like this:

interface thing_message {
  pressure_volts: number;
  temperature: number;
  state: string;
}

The Gateway starts building the following message:

const message = {
  sensor: {
    pressure_volts: 5,
    temperature_volts: 6,
    state: "on",
  },
};

Let’s write the function for a Calculation named pressure_psi:

(sensor.pressure_volts * 20) / 10;

Sensor Namespace

In the above formula we have access to the current IoT Connected Asset’s aggregated sensor data under the namespace sensor. There are 4 additional namespaces covered in Namespaces.

The Gateway message now looks like:

const message = {
  sensor: {
    pressure_volts: 5,
    temperature_volts: 6,
    state: "on",
  },
  calculation: {
    pressure_psi: 10,
  },
};

Now let’s write a formula for an alert on pressure named overpressure:

sensor.state === "on" && calculation.pressure_psi > 15;

JavaScript

Any valid JavaScript which returns a value can be used in these Calculations and Alerts. Take a look at JavaScript Basics for help on basic operators.

Our Gateway message now looks something like:

const message = {
  sensor: {
    pressure_volts: 5,
    temperature_volts: 6,
    state: "on",
  },
  calculation: {
    pressure_psi: 10,
  },
  alert: {
    overpressure: false,
  },
};

This is the basic structure you’re putting together when building your Thing Type specification.

Namespaces

There are 5 base namespaces which can be used to access data from these formulas:

sensor: Provides access to all the latest aggregated sensor values. Aggregation is defined by the Thing Type specification Salesforce, ServiceNow.
calculation: Provides access to all the latest calculated values. Calculations are defined by the Thing Type specification Salesforce, ServiceNow.
alert: Provides access to all the latest alert values. Alerts are defined by the Thing Type specification Salesforce, ServiceNow.
context: Provides access to all the latest context values. Context is defined by the Context settings Salesforce, ServiceNow.

Context settings.

twin: Provides access to all the the following values:

role

the Digital Twin role for the referenced IoT Connected Asset

Priority

When specifying calculations and alerts in the thing-type specification (Salesforce, ServiceNow), the priority defines the execution order of each calculation/alert. Alerts are always evaluated after all calculations. Within each group (calculations and alerts), formulas are evaluated in priority order from smallest (0) to largest (infitinity). A calculatoin with priority 0 will be evaluated before a calculation with priority 1 and so on. For elements with equal priority, their order relative to each other is arbitrary. So in the following example:

calcA: priority = 0
calcB: priority = 10
calcC: priority = 10
calcD: priority = 11

… calcA is evaluated first followed by calcC and calcB (in no defined order), then finally calcD is evaluated. Once all the calculations are evaluated, the alerts are then evaluated.

When referring to calculations which are evaluated later in the cycle from within calculations which happen earlier, there will be a unit-delay in the value retrieved.

Example:

calcA: priority = 0, formula = (calculation.calcB === undefined) ? 0 : calculation.calcB + 1

calcB: priority = 1, formula = calculation.calcA + 1

On the first pass, calculation.calcB will be undefined, so calcA will be 0, calcB is then 1

On the second pass, calcA will be 2, calcB will be 3

… and so on

Specification Metadata Access

In general, when you reference a sensor, calculation, or alert within a formula, it implicitly retrieves it’s current value (i.e. calculation.calcAbc implicitly becomes calculation.calcAbc.value). Alternatively, there are other metadata which can be retrieved from the given element.

In addition to the implicit value, the following parameters are available:

Sensor
- name: the calculation name (e.g. sensor.sensorAbc.name = "sensorAbc")
- label: the calculation label (e.g. sensor.sensorAbc.label = "Sensor ABC")
- dataType: the calculation data-type (e.g. sensor.sensorAbc.dataType = "Number")
- aggregateType: the sensor’s aggregation-type (e.g. sensor.sensorAbc.aggregateType = "Seconds")
- aggregateFunction: the sensor’s aggregation-function (e.g. sensor.sensorAbc.aggregateFunction = "MAX")
- aggregateInterval: the sensor’s aggregation-interval (e.g. sensor.sensorAbc.aggregateType = 300)
- isStored: true if the sensor is stored in the cloud (e.g. sensor.sensorAbc.isStored = true)
- storageDataType: the cloud storage type (e.g. sensor.sensorAbc.isStored = "Double")
Calculation
- name: the calculation name (e.g. calculation.calcAbc.name = "calcAbc")
- label: the calculation label (e.g. calculation.calcAbc.label = "Calculation ABC")
- formula: the calculation formula (e.g. calculation.calcAbc.formula = "1 + 1")
- priority: the calculation priority (e.g. calculation.calcAbc.priority = 14)
- isActive: true if the calculation is active (e.g. calculation.calcAbc.isActive = true)
- isStored: true if the calculation is stored in the cloud (e.g. calculation.calcAbc.isStored = true)
- storageDataType: the cloud storage type (e.g. calculation.calcAbc.isStored = "Double")
Alert
- name: the alert name (e.g. alert.alertAbc.name = "alertAbc")
- label: the alert label (e.g. alert.alertAbc.label = "Alert ABC")
- alertType: the alert-type (e.g. alert.alertAbc.alertType = "Threshold")
- alertInterval: the interval which the alert re-drives to ServiceNow (e.g. alert.alertAbc.alertInterval = 3600)
- formula: the alert formula (e.g. alert.alertAbc.formula = "calculation.calcAbc > 1")
- priority: the alert priority (e.g. alert.alertAbc.priority = 14)
- isActive: true if the alert is active (e.g. alert.alertAbc.isActive = true)
- isStored: true if the alert is stored in the cloud (e.g. alert.alertAbc.isStored = true)

Examples

Example 1 Constant

Name: example1

Description: Always return a constant value for the calculation or alert.

Formula:

"hello world";

Result: constant { ... example1: 'hello world' ... } in each message

Example 2 Basic Arithmetic

Name: example2

Description: Scale sensorA

Formula:

sensor.sensorA * 10 + 2;

Result:

{
  "sensorA": 3,
  "example2": 32
}

Example 3 Conditional

Name: example3

Description: If the IoT Connected Asset’s sensorA is over 10, calculate, otherwise return 0.

Formula:

sensor.sensorA > 10 ? sensor.sensorB * 50 : 0;

Results:

{
  sensorA: 3,
  sensorB: 6,
  example3: 0
}

{
  sensorA: 11,
  sensorB: 6,
  example3: 300
}

Alternate

if (sensor.sensorA > 10) {
  return sensor.sensorB * 50;
} else {
  return 0;
}

Example 4 Digital Twin

Name: example4

Description: If the IoT Connected Asset’s parent is powered on, calculate, otherwise return 0.

Formula:

$parent.calculation.powerOn ? sensor.sensorB / $parent.sensor.inputVoltage : 0;

Results:

parentId: {
  sensor: {
    inputVoltage: 12
  },
  calculation: {
    powerOn: true
  }
}

{
  "sensorB": 6,
  "example4": 0.5
}

parentId.sensor.inputVoltage: 0
parentId.calculation.powerOn: false

{
  "sensorB": 6,
  "example4": 0
}

Alternate

if ($parent.calculation.powerOn) {
  return sensor.sensorB / $parent.sensor.inputVoltage;
} else {
  return 0;
}

Example 5 Context

Name: example5

Description: If the IoT Connected Asset’s entitlement level is either Platinum or Gold, evaluate the threshold, otherwise return false.

Formula:

["platinum", "gold"].includes(context.entitlementLevel.toLowerCase())
  ? calculation.someValue > 100
  : false;

Results:

context.entitlementLevel = "Gold";

{
  "someValue": 101,
  "example5": true
}

context.entitlementLevel = "Silver";

{
  "someValue": 101,
  "example5": false
}

Alternates

if (["platinum", "gold"].includes(context.entitlementLevel.toLowerCase())) {
  return calculation.someValue > 100;
} else {
  return false;
}

function isCovered(level) {
  const coveredLevels = ["platinum", "gold"];
  return coveredLevels.includes(level.toLowerCase());
}

if (isCovered(context.entitlementLevel)) {
  return calculation.someValue > 100;
} else {
  return false;
}

Docs: Javascript Basics

Mon, 01 Jan 0001 00:00:00 +0000

Additional Resources

Documentation on JavaScript is plentiful. Below are some great resources to get the latest or dig deeper into the features of the language.

Mozilla JavaScript Docs

Or check out our curated list of basic JavaScript functionality.

Quick Reference

Docs: Core Libraries

Mon, 01 Jan 0001 00:00:00 +0000

This section provides details on using the Core libraries in Calculations and Alert Conditions.

Generally these libraries are available under the core namespace.

Example

Here we describe a calculation which will latch to true if sensor > 10 and stay true until sensor < 8

calculation = core.logic.latchROS(sensor > 10, sensor < 8)

Available Libraries

Docs: Digital Twin

Mon, 01 Jan 0001 00:00:00 +0000

To reference data from other IoT Connected Assets from a given IoT Connected Asset’s calculations and alerts, the following keys provide a way of traversing your Digital Twin hierarchy. From any of the following keys, you can define a role-path to the role which you are interested in.

Available Keys

`$self`

Retrieve a reference to another component with respect to “myself”.

Usage

// Get Reference to My Child's Child
$self.child_A.childs_child;

// Get Reference to My Child's Child
// **Note** this is illustrative only, as you can access sensors /
// calculations / directly without this
$self;

// Use reference to access the aggregated value of `sensorA`
$self.child_A.childs_child.sensor.sensorA;

`$parent`

Retrieve a reference to another component with respect to “my parent”.

Usage

// Get Reference to My Sibling
$parent.sibling_A;

// Get Reference to My Parent directly
$parent;

// Use reference to access the aggregated value of `sensorA`
$parent.sibling_A.sensor.sensorA;

`$root`

Retrieve a reference to another component with respect to “my top-level root”.

Usage

// Get Reference to My Family Member
$root.someRole.subassembly;

// Get Reference to My Root directly
$root;

// Use reference to access the aggregated value of `sensorA`
$root.someRole.subassembly.sensor.sensorA;

`$context`

Retrieve a reference to another component by referencing an External ID defined in a Context Field. When using the $context key, you must supply a context field name. Formula processing will assume the referenced field is the External ID to another IoT Connected Asset and attempt to access its data.

Usage

// Get Reference to an arbitrary IoT Connected Asset's child
$context.contextFieldName.child_A;

// Get Reference to an arbitrary IoT Connected Asset directly
$context.contextFieldName;

// Use reference to access the aggregated value of `sensorA`
$context.contextFieldName.sensor.sensorA;

Examples

Digital Twin Definition

Let’s assume we have the following Digital Twin Role Hierarchy:

(role : thingType)
bike : Bicycle
  ├ rearWheel : Wheel
  │   ├ brake : Brake
  │   └ tire : Tire
  │
  ├ frontWheel : Wheel
  │   ├ brake : Brake
  │   └ tire : Tire
  │
  └ bottomBracket : BottomBracket
      ├ crank : Crank
      ├ bearing : Bearing
      ├ leftPedal : Pedal
      └ rightPedal : Pedal

Digital Twin Instantiation

Let’s then assume the following instance of this Digital Twin:

(externalID : role)
BIKE001 : bike
  ├ WHEEL001 : rearWheel
  |   ├ BRAKE001 : brake
  |   └ TIRE001 : tire
  |
  ├ WHEEL002 : frontWheel
  |   ├ BRAKE002 : brake
  |   └ TIRE002 : tire
  |
  └ BRACKET001 : bottomBracket
      ├ CRANK001 : crank
      ├ BEARING001 : bearing
      ├ PEDAL001 : leftPedal
      └ PEDAL002 : rightPedal

Referencing Data

On the Bicycle thing type let’s write the formula for a Calculation named tirePressureDifference:

$self.frontWheel.tire.sensor.pressure - $self.rearWheel.tire.sensor.pressure;

Then in the Tire Thing Type (which will execute for each tire) let’s add the following formula for an Alert named tirePressureAbnormal:

if ($root.calculation.tirePressureDifference > 10) {
  // if parent is 'rearWheel', sibling is 'frontWheel' else sibling is 'rearWheel'
  const siblingPressure =
    $parent.twin.role === "rearWheel"
      ? $root.frontWheel.sensor.pressure
      : $root.rearWheel.sensor.pressure;

  // check if I'm the "low" one
  return sensor.pressure < siblingPressure;
} else {
  return false;
}

Some further examples of traversing this Digital Twin:

From PEDAL001

$parent; // BRACKET001

$parent.bearing; // BEARING001

$parent.$parent.frontWheel; // WHEEL002

$root.frontWheel; // WHEEL002

From WHEEL002

$root.bottomBracket; // BRACKET001

$self.tire; // TIRE002

Docs: State Machines

Mon, 01 Jan 0001 00:00:00 +0000

Components

Machines

A collection of States, Transitions and Actions. At the end of any given step each serial-sub-state within a machine will contain exactly one active state.

States

A state encapsulates a set of logic to be evaluated when active. States can be hierarchical. A parent state is active if any of its child-states are active. Each state has three phases of execution, entry, during, and exit. When a State changes from inactive to active, its entry actions are evaluated. When a State starts active and ends active (in a given step), its during actions are evaluated. When a State changes from active to inactive, its exit actions are evaluated.

Actions

Actions define processing within various scopes. Actions can be used to update the Machine local variables, set global variables, or make call-outs to external web services.

Transitions

The Transition defines a path between two states, the From-State and the To-State. Once a transition is executed, the From-State becomes inactive and the To-State becomes active. Transitions can include Actions which are evaluated once the transition is executed

Events

An alternate input-scheme which can be used instead-of or alongside local variables. Events can be useful if your approach includes combining several calculations ahead of evaluating the state-machine. The catch is that only a single Event can be handled by the state-machine for any given step.

Execution

State Machine Execution

Initialization

Once a Machine is created, it will sit in an uninitialized state, whereby no state is active and no transitions have been evaluated. If the first call to myMachine.step() happens before the machine is initialized, it will automatically initialize the Machine. It’s best practice to explicitly initialize the Machine, once construction is complete by calling myMachine.initialize().

During initialization, at each level in the hierarchy, the initial state is determined during construction by explicitly specifying {initial: true} in the desired state

if two states at the same level are specified as initial, the last one specified wins

From the top of the hierarchy down, each initial-transition is identified and evaluated. The machine is fully initialized once every state has the appropriate number of active states as defined by it’s Decomposition (serial vs parallel).

Step

Once a Machine is initialized, it can be “stepped” through time. Each step represents a discrete point in time (in our specific case, the machine is “stepped” upon receipt of each IoT Message).

During the step, all Transitions from the active state hierarchy are evaluated from the top, down. That is to say, given active state, B.B.B, all Transitions out of the top state B are evaluated in priority order, executing the first Transition who’s condition expression evaluates to true or who’s condition doesn’t exists (i.e. an Unconditional Transition). If no Transitions at level B are to be executed, all Transitions at the B.B level are evaluated in the same manor until either a Transition is identified to evaluate, or no Transitions are to be taken.

If a Transition is identified to evaluate, first the exit actions in the lowest level From-State are evaluated, then the exit actions are evaluated up the hierarchy until the lowest-common State between From-State and To-State. Meaning in a transition from B.B.B to B.B.A, only the exit actions from B.B.B are evaluated (since B.B is never exited during the transition). Whereas if transitioning from B.B.B to A.B, the exit actions at B.B.B, B.B, and B are evaluated.

If no Transitions are to be evaluated, the during actions of the current active state are evaluated from the top, down.

Examples

Full Example

Illustrative (not functional) State Machine containing all possible features of the State Machine library.

Initialization:

The initial transition into B is evaluated and the local variable, time0 is set to now.
B is activated.
B entry actions are evaluated, incrementing the machine variable, bEntry
States B.A and B.B run in parallel (indicated by the dashed border). B.A and B.B are activated.
So, the initial transitions into B.A.B and B.B.B are executed.
Both B.A.B and B.B.B are activated.

Step 1:

Both B.A.B and B.B.B are active.
First there exists a transition at the top level, somethingElse < 50. If this evaluates to true, then all active children of B are exited and deactivated from the bottom up. For this example let’s assume somethingElse = 100, so this transition will not be executed.
Since the transition from B.B.B to B.B.A is unconditional, it is marked for evaluation.
B.B.B exit actions are evaluated (local variable, bbbExit is incremented)
B.B.B is deactivated
If there were any actions defined on this transition, they’d be evaluated here.
B.B.A is activated
B.B.A entry actions are evaluated (local variable, bba is now true)
B during actions are evaluated (bDuring is incremented)

Step 2:

Both B.A.B and B.B.A are active.
There are two transitions out of B.B.A (priority can be set on transitions to handle this case). If something < 10, then transition 1 would be marked for evaluation, otherwise, transition 2 is unconditional, so it will be marked for evaluation by default. For this example, let’s say something = 6, so transition 1 is marked for evaluation.
B.B.A is deactivated
B.A.B is deactivated
B.A is deactivated
B.B is deactivated
B.B exit actions are evaluated (bbExit is incremented)
B is deactivated
If there were any actions defined on this transition, they’d be evaluated here.
A is activated
A.A is activated

Advanced Topics

State-Decomposition

At any given level in the state-hierarchy, there are two possible modes of execution: Serial (default) and Parallel. Serial decomposition defines that at a given level, there is only ever a single active state at the end of any give step. Contrary, Parallel decomposition defines that all states at a given level are active. In the examples below, the Serial State Machine will only ever have a single active state (e.g. 'A.B' or 'B.A.B'), whereas the Parallel State Machine will have 3 active states at any given time (e.g. ['A.A', 'B.A.B', 'B.B.A'] etc.)

Serial State Machine

Parallel State Machine