Exposed services reference

This document describes how to interact with the exposed external services in the cloud code.

  • email: Sends an email.
  • twilio: Voice and SMS.
  • Twitter: Send a Tweet.
  • httpRequest: Sends an http request
  • console: Logs in your code
  • analytics.events: Allows to create and retrieve events
  • analytics.kpis: Allows to create kpis
  • thethingsAPI: Allows to Read and Write on a device resource
  • DataSet: Represents the data returned from analytics.events.getByName
  • moment: date operations from Moment.js
  • async: Utility module which provides powerful functions for working with asynchronous JavaScript.
  • Geolib: Provide basic geospatial operations from geolib. Let's you build geofencing for example.

email

Sends an email. You have to introduce your service provider credentials.

email(credentials, options)

  • credentials: object
    • service: one of 'SendGrid' | 'Mandrill' | 'SES' | 'Gmail'
    • auth: object
      • SendGrid: {api_user: string, api_key: string}
      • Mandrill: {apiKey: string}
    • SES: {accessKeyId: string, secretAccessKey: string, region: string (ex: 'us-west-2')}
      • Gmail: {user: string, pass: string}
  • options: object
    • from : string (sender email)
    • to: string (receiver email)
    • subject: string
    • text: string

SMS and voice calls with twilio

This service lets you send SMS and make voice calls. You have to introduce your twilio credentials.

twilio Examples

Twitter

This service lets you send a Tweet to your Twitter account. You have to introduce your Twitter credentials.

httpRequest

Sends an http request to an external web service.

httpRequest(request, body, callback)

  • request: object
    • host: string
    • path: string
    • port: number || 80
    • method: string || 'GET'
    • headers: object {'header-name': 'header-value'}
  • body: string
  • callback: function(error, headers, data) (optional)
    • error: tells if the request has got some error
    • headers: object response headers
    • data: response data

If no callback is provided the request will be executed too and errors will be redirected to the console.

console

Sends the paramer data to the developers console.

console.log(arg1, arg2, ..., argN)

console.error(arg1, arg2, ..., argN)

console.log(arg1, arg2, ..., argN)

  • argX: (string|number|object)

analytics.events

Allows to create and retrieve events.

analytics.events.create(event)

  • event: object
    • name: string
    • value: string

analytics.events.getByName(name, callback)

  • name: string
  • callback: function(error, data)
    • error: (null|string) if something has gone wrong
    • data: DataSet

The last hour/day events with eventName = name will be retrieved. Each element of the DataSet will have createdAt and value elements.

analytics.events.getValuesByName(name, callback)

  • name: string
  • callback: function(error, data)
    • error: (null|string) if something has gone wrong
    • data: DataSet

The last hour/day events with eventName = name will be retrieved. Each element of DataSet will be the value of the event with that name.

analytics.kpis

Allows to create custom kpis.

analytics.kpis.create(name,value)

  • name: string
  • value: (string|number|object)

thethingsAPI

Allows to Read and Write on a device resource. Also lets you call functions from triggers and jobs. Last you can get the things of a product.

thethingsAPI.thingRead(thingToken, resourceName, callback)

  • thingToken: string
  • resourceName: string
  • callback: function(error, result)
    • error: tells if the request has got some error
    • result: response data

thethingsAPI.thingWrite(thingToken, values, callback)

  • thingToken: string
  • values: array(Object,...)
    • Object: {key:'resourceName', value:(string|number|object)}
  • callback: function(error, result)
    • error: tells if the request has got some error
    • result: response data

thethingsAPI.getProductThings(callback)

  • callback: function(error, things)
  • error: tells if the request has got some error
  • things: response data. Array of objects containing thing data like thingToken, id, etc.

thethingsAPI.cloudFunction(fname, params, callback)

  • fname: string. The function name.
  • params: Any type. The input.
  • callback: function(error, result)
  • error: tells if the request has got some error
  • result: response data

thethings API Example

DataSet

This class represents an abstraction of data returned from analytics.events.getByName This class allows chaining.

Note: * means any type of element.

DataSet DataSet.prototype.map(fn)

  • fn: * function(value)

    • value: * one element from the DataSet

    Applies fn to each value in the DataSet. i.e. ResultDataSet[i] = fn(DataSet[i])

DataSet DataSet.prototype.filter(fn)

  • fn: boolean function(value)

    • value: *

    Returns a new DataSet where its elements are the ones where fn(oldDataSet[i]) == true

Any DataSet.prototype.reduce(fn, init)

  • fn: * function(prev, cur)
    • prev: * previous aggregated value
    • cur: current value
  • init: * initialization value

    Returns fn(...fn(fn(fn(init, DataSet[0]), DataSet[1]), DataSet[2]),...) but the execution order is undefined. i.e. fn should be commutative and associative.

    For example, the product of all the elements of the dataset would be:

DataSet DataSet.prototype.sort(fn)

  • fn: number function(a,b) (optional) comparing function returns < 0 if a goes before b

DataSet DataSet.prototype.take(n, s)

  • n: num elements to take
  • s: num elements to skip (optional)

Returns a new DataSet with the first n elements (and skiping s) from the old.

DataSet DataSet.prototype.deltaR(fn, last)

  • fn: * function(cur,next) (optional) function that is applied to each pair of consecutive elements and stored in cur
  • last: * (opitional) a virtual element to add temporary in the last element of the DataSet

    Applies fn to each pair of consecutive elements in the DataSet. Default value for fn:

    function(cur, next){
      if(cur.value){
        return next.value - cur.value
      }else{
        return next - cur
      }
    }

DataSet DataSet.prototype.deltaL(fn, first)

  • fn: * function(prev,cur) (optional) function that is applied to each pair of consecutive elements and stored in cur
  • first: * (opitional) a virtual element to add temporary in the first element of the DataSet

    Applies fn to each pair of consecutive elements in the DataSet. Default value for fn:

    function(prev, cur){
      if(cur.value){
        return next.value - cur.value
      }else{
        return next - cur
      }
    }

Number DataSet.prototype.count()

Returns the number of elements in the DataSet

Number DataSet.prototype.sum()

Returns the sum of all elements in the DataSet

Number DataSet.prototype.prod()

Returns the product of all elements in the DataSet

Number DataSet.prototype.avg()

Returns the average of all elements in the DataSet

Number DataSet.prototype.wavg()

Returns the weighted average of all elements in the DataSet. That is, weight each value with the time it was active. For example, if there have been 20 degrees during 2 hours and 15 degrees during 1 hour. Then wavg() will be 2/3 20 + 1/3 15 = 18.3. Needs from getByName.

Number DataSet.prototype.max()

Returns the max element of the DataSet

Number DataSet.prototype.min()

Returns the min element of the DataSet

DataSet DataSet.prototype.sample(p)

  • p: number 0 <= p <= 1

    Returns a new DataSet where each element has probability p to be in the new DataSet

Array DataSet.prototype.percentiles(splits, fn)

  • splits: number
  • fn: * function(value)

    Splits the data in splits parts, gets the median (if were previously sorted) of each one and returns fn(median)

Array DataSet.prototype.collect()

Returns the data in form of array