Cloud Code Functions

Functions are snipets of code executed when an API REST endpoint is called. They can also be called from other parts of the cloud code like triggers and jobs. They are useful to encapsulate business logic that you don't want into the devices.

Each function must contain a function main(params, callback)

Where:

params is the input of the function which can be a string, object, array,...

callback(error, result) is a function to be called when the function ends. Can contain a parameter string error if the funciton needs to report an error. If the error is null it can contain a result which will be returned as a response.

The execution of a function is limited to 15 seconds. If the execution takes longer, the server will end the sandbox

Calling a Function

There are two ways to call a function, from the API REST (either HTTP or CoAP) and from the Cloud Code (jobs and triggers).

// Using HTTP request

curl -i -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"params" : { {THE FUNCTION INPUT GOES HERE} }}' \
  -X POST "https://api.thethings.io/v2/things/:thingToken/code/functions/{ {fname} }" -k

// Using CoAP request

coap post 'coap://coap.thethings.io/v2/things/{ {thingToken} }/code/functions/{ {fname} }/' -p '{\"params\": {\"payload\" : \"message\"}}'

To call the function from a trigger, a job or another function you can do:
thethingsAPI.cloudFunction(fname, params, callback)

• fname: string The function name.
• params: Any type The input.
• callback: function(err,result) If the execution was successful err should be null.
  The function input can be any valid type for JSON (Number, String, Boolean, Object, Array or null).

Here are some examples. Of course you can also do useful things like turning miles to kilometers with them.

Answer to the Ultimate Question of Life, the Universe, and Everything

When you need to know any answer you can simply do:

function main(params, callback){
  callback(null, params.quote+42)
}

{
  params: {
    "quote": "the answer to life the universe and everything is "
  }
}

Generate Events

You can generate events from inside the code. The following code generates a simple event which stores the value to an event called 'temperature'. To be later retrieved from a job:

function main(params, callback){
  analytics.events.create({name:'my-event', value:params})
  callback()
}

The Always Erred Function

This function is always returning errors:

function main(params, callback){
  callback("I'm in bad mood")
}

Some Asynchronous Stuff

You may be wondering why you need to call a callback instead of the classical return. With callback you can do things like:

function main(params, callback){
  console.log('test: ', params)
  //you can preprocess the input(params) here

  httpRequest({
    host : 'api.citybik.es',
    path : '/bicing.json'
  },params, function(err, result){
    //and postprocess the api result here before sending to your thing
    if (err) callback(err)

    if (result.headers['content-type'] == 'application/json') {
      result.result = JSON.parse(result.result)
    }

    callback(null, result)
  })
}