Cloud Code Parsers

Parsers or decoders 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 like they were a serverless function. They are useful to encapsulate business logic that you don't want into the devices and transform the device structure message and format to a the format that thethings.io understands.

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

Where:

params is the input of the parser 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 parser is limited to 30 seconds. If the execution takes longer, the server will end the sandbox

Calling a Function

There are two ways to call a parser, from the API REST and from the Cloud Code (jobs and triggers) like a function.

// 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

To call the parser from a trigger, a job or another parser 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 Parser

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)
  })
}