SDK context

Context description

The context in Carriots SDK is a data structure holding information hydrated by Carriots for execution-time use. It allows building expressions and rules with direct access to an event context information.

Scripts are executed when an event is fired and a listener is bound to that event. This event’s information is accessible via the context variable. Different events have different contexts. For example, when a stream is received the context may differ from the one of change status event caused by the absence of a stream. Refer to our Device Inner Status documentation page for more information about how devices may change their status.

For example, for accessing stream’s data content when a data received event is fired in a listener code you can use variable. See the example below to have a snapshot.

Context usage example

This is an example of checking context information by printing "context" content in a script by setting a listener like this one:

If expression: true

Then expression:

If this listener is bound to a device and "listens" to a Data Received Event then a stream sent to that device will send an email will full context information data.

When a stream is sent to the associated device an email will be sent with something like:

Data received & data persisted events context

When a stream is received at Carriots, no matter if its a data stream or a status stream, there are two events raised in its processing:

  • Data Received Event - when the stream is received, BEFORE persistence
  • Data Persisted Event - when the stream is persisted in Carriots DB

In both cases there is a stream involved and its data is stored in the context. This is an example of that context:

The difference between the context in a Data Received Event and a Data Persisted Event is the key id_developer and its corresponding value in the envelope. This is the true id_developer value after stream persistence.

Context content:

Key Content
session Filled with a session if the script is executed in web console
envelope It contains the envolope information:
- id_developer: the stream id_developer (only for persited streams)
- protocol
- device: device id developer
- at: stream timestamp
- checksum: stream data hash
- _t: "str" for data streams or "sta" for status streams
data Stream data
hierarchy Device hierarchy (unordered)
meta Request metadata.
Useful information about the request metadata:
- ve = version
- ur = URL
- me = method
- he = HTTP headers
- ho = host
- pr = protocol

Device status change event

When a device changes its inner status, Carriots raise an event and injects the context to be used in listeners and rules scripts. A status change implies to statuses: one before the change takes place and another when the change is done. For example, a device can be in a "no_data" status and change to "disconnected" or from "OK" to "no_status" and so on.

So, there is 2 status in a "change state" event context:

  • - device’s status BEFORE the event
  • - device’s status AFTER the event

Please refer to our Device Inner Status documentation page for more details.

This is a full context example. The device test@cariots has changed from ok to disconnected:

Usage example that sends an email with different subjects in function of a devices status change: