Code
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:
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:
1. 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” |
2. 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.
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.
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 |