Code

Introduction

The ClearBlade IoT Platform utilizes a microservices model powered by a Code Engine. This Code Engine is JavaScript, and has several built-in integrations to interact with your IoT assets. Adhering to microservice practices, a new execution context is sandboxed, created upon invocation, and once complete, is destroyed.

Within the context of the ClearBlade IoT Platform, a Service is synonymous with a microservice, and will be used extensively across the documentation.

There are two types of Code assets:

For a tutorial on how to set up code services, click here

Purpose

Microservices are a software development technique that allow for a high degree of modularity, scale, and paralleization - all of which are essential for effectively building and running full-scale IoT Applications.

Libraries

Libraries are reusable sets of code that can be imported by one or more code services.

Native Libraries

Native Libraries are available in every System, and have an underlying implementation in Golang. Each library is optimized for computational performance.

These libraries can be imported using Requires

Library Desc Docs
clearblade Interacts with Collections, Messaging, Users, Edges, Devices View docs
log Appends messages to a log View docs
http Makes outbound HTTP/S requests View docs
geo Geospatial Computation Library View docs
crypto Creates cryptographical hashes View docs
file_writer Write files to host filesystem View docs
jsutil JS Utility Library View docs
mailer Send email directly from host machine View docs
net_cb Net library View docs
oauth2_lib OAuth Utility Library View docs

Custom Libraries

A developer can create his or her own custom library with custom logic.

Services

A Code Service, or Service, is a short-lived microservices that is expected to complete in under 30 seconds.

Lifecycle

Invocation

A Service can be invoked in any of the three ways:

  1. A REST request to the API Endpoint
  2. Trigger Event
  3. Timer Event

Our SDKs can be used as a REST Client to accomplish the first REST option

Context

Each Code Service service has a name, and that name corresponds to an autogenerated function name.

For example, a code service named analyze will have an autogenerated function like so:

function analyze(req, resp) {}

This function will have two parameters, similar to Node’s Express library:

req

req is an object containing the following contextual values:

key desc type example
userEmail Email of user who invoked the service string “user@clearblade.com”
params JSON with parameters, structure is based upon type of Invocation Object {“key”:“value”}
systemKey System Key for system in which code service is running string e095a19d0b94e48dee9bff87e5fd01”
systemSecret System Secret for system in which code service is running string “E095A19D0B9ACD9EFA86AEEDFCC001”
userToken Invoking user’s OAuth token string “U1hNa7o4bEXpiE4aGhb-79MQv4…”
isLogging Whether logging is enabled boolean true
userid internal uid associated with invoking user string “fc8cfcea0a96ebebc7f5d4edd414”

resp

resp is an object that is used to return values and exit the Code Service with two methods:

resp.success = function (object | string){} resp.error = function (object | string ){}

function analyze(req, resp) {
  var message = "Everything went well!";
  resp.success(output); // Service exits successfully with "Everything went well!"
}

function analyze(req, resp) {
  var message = "It broke!";
  resp.error(error); // Service exits with failure with "It broke!"
}

Exit

The Code Service will exit executing either resp.success or resp.error.

Note: By default, if no exit method is called and execution reaches the end, resp.success will be called to exit

Requires

A Code Service can import a Library using the Requires feature. In the Service settings, you can select one or more libraries to import, and that code is accessible from within the Code Service.


The same library can be used for multiple code services

Debugging

There is no native support for debugging line-by-line. Recommended to use log method extensively, like so:

function ServiceA(req, resp) {
  log("Something happened");
  resp.success("All done");
}

Settings

Execution Timeout

Code Services are usually used as microservices, and expected to have a lifecycle of under 30 seconds. However, this execution timeout can be extended to perform such operations as mentioned in Concurrency

Concurrency

The number of Code Services that can run at a given time. Any more than this number will kill the oldest code service.

Code Service can be configured to be a Long Running Code Service, meaning the code service will run indefinitely. This allows for the following high performance use cases:

  • Code Service subscribes to MQTT Topic and performs operations at higher rate than a trigger
  • Data generation
  • Finite state machine operations, where local variables are updated upon message updates

Run as User

If Code Services needs escalated privileges, you can use an administrative user to invoke code services

Failed Runs

If a Code Service exits with resp.error, or throws an uncaught error, it will be stored in Failed Runs. A developer can then fix any issues, and retry that failed run with the same input parameters.

Standard Javascript Functions (es5.1)

Method not supported Alternative
setTimeout(),setInterval() Not supported at all
atob(), btoa() buffer-node-js library
promises q-promise-library

Events

Events are actions or occurrences that happen in the ClearBlade System, response to them through execution of the associated Code Service. ClearBlade supports two types of events:

Timers

Timers provide a mechanism where a ClearBlade code service can be scheduled to execute at certain time intervals. Timers are similar to Unix cron jobs, with a similar scheduling mechanism.

Some example Timer configurations:

  • Run forever every five minutes starting now
  • Run 26 times every two weeks starting Friday, December 25th, 2018
  • Run once at midnight

Triggers

Triggers are a mechanism that tie an action, called a Trigger Source, to the invocation of a code service. The trigger source and payload information is passed into a code-service as req.params. For example: A trigger on Messaging - Publish as the source will have the following object passed to the Code Service as payload.

"params": {
    "topic": "ClearBladeTopic",
    "body": "214.312",
    "userId": "8e89e2af0fc9cbeadfd6afb501",
    "trigger": "Messaging::Publish"
}

Trigger Source

When you define a trigger, you provide the following information:

Asset Category Action
Messaging Publish Publish
Messaging Subscriptions Upon Subscribe
Messaging Subscriptions Upon Unsubscribe
Messaging Connection User Connected
Messaging Connection User Disconnected
Messaging Connection Device Connected
Messaging Connection Device Disconnected
Data Table Created
Data Table Updated
Data Table Deleted
Data Item Created
Data Item Updated
Data Item Deleted
User n/a Created
User n/a Updated
User n/a Deleted
Device n/a Created
Device n/a Updated
Device n/a Deleted