Overview

The Service Plugin API enables developers to create plugins that consumes device/sensor data, process them and come up with a result. The process can be something as simple as data transformation, a call out to an external API or Web Service, or any other form of data analysis and/or enrichment. The output from the process is then piped to the next plugins in the data pipeline where the Service plugin is attached to. This article aims to provide detailed information on the APIs available for Service Plugins and how to build one.

Starting a Node.js Service Plugin Project

To easily create a plugin project scaffolding for Service plugins, Reekoh has provided a generator tool which can be used like:

cd path/to/your/project-folder

yo reekoh-node:service

Building the Plugin

The file named app.js is where everything starts. To use the Service Plugin API, one starts by creating a service instance as seen on the scaffolding's app.js file.

app.js

'use strict'

const reekoh = require('reekoh')
const plugin = new reekoh.plugins.Service()

plugin is now an instance of a Service with the necessary properties, methods, and events for creating a Service plugin. Details of the Service instance' properties, methods and events are specified in the following sections.

Properties

Specified below are the properties of a Service instance which are injected for use in your plugin.

• config {object} - The custom plugin configuration values as requested from and specified by the end user. For more about plugin configurations, please see the Packaging & Submission section.

Events

Specified below are the events that a Service instance is able to emit based upon operations that are happening on the platform pipelines.

'ready'

This event is emitted when the Service instance has fully initialised. This is usually the event where one listens to and puts the code to bootstrap the plugin i.e. create a client to an API or Web Service.

Sample Code

let client

plugin.on('ready', () => {
  client = createClient(plugin.config.apiKey)

  client.on('connected', () => {
    plugin.log('Client is now connected to the service')
  })
})

 'data'

This event is emitted when device/sensor data is received. This is the event to listen to in order to get real-time data feed from the connected devices. The data received will be the input for the process.

Arguments

• data {object} - the data received from the pipeline. Can be raw device/sensor data but can be processed data too depending on how the user has designed the pipeline.

Sample Code

plugin.on('data', data => {
  client.callMethod(data).then(result => {
    plugin.pipe(data, result)
  })
})

Methods

Specified below are Service API methods that you can use for your plugin to relay information and initiate operations on the platform.

pipe(data, [sequenceId])

Invoke this method to transmit the data through the next plugins in the pipeline for further processing or integration.

Arguments

• data {object} - the original data received from the pipeline.
• result {object} - the result of the process or operation.

Returns

• Promise - which is fulfilled once the data has been transmitted through the pipeline

Sample Code

plugin.on('data', data => {
  client.callMethod(data).then(result => {
    plugin.pipe(data, result)
  })
})

setState(state)

Invoke this method to set the plugin's state. State can be used to store additional information or metadata for the plugin. It can also be used as cache for any information that needs to be stored temporarily.

Arguments

• state {any} - state to be stored. Can be anything - object, array, string, number etc.

Returns

• Promise - which is fulfilled when the state has been submitted for storage.

Sample Code

let client

plugin.once('ready', () => {
  client = createClient(plugin.config.apiKey)

  client.on('connected', () => {
    plugin.log('Client is now connected to the service')
  })

  plugin.setState({
    config: plugin.config,
    otherMetadata: {
      calls: 0
    }
  })
})

getState()

Invoke this method to retrieve the contents of the plugin state. 

Returns

• Promise (state {any}) - resolves or returns the contents of the plugin's state.

Sample Code

let client

plugin.on('data', data => {
  plugin.getState().then(state => {
    console.log(state)
  })
})

log(logData)

Invoke this function to log any information. Can be useful for debugging. Logs are found under the Logs module or in each plugin instance in the Pipeline Studio.

Arguments

• logData {string | object} - The information to be logged.

Returns

• Promise - fulfilled when the log data has been submitted to the platform for recording.

Sample Code

plugin.on('data', data => {
  plugin.log('Received data')
  plugin.log(data)

  client.send(data)
})

logException(err)

Invoke this function to log errors/exceptions. Can be useful for debugging. Error/exception logs are found under the Logs module or in each plugin instance in the Pipeline Studio. 

Arguments

• err {error} - The error to be logged.

Returns

• Promise - fulfilled when the error data has been submitted to the platform for recording.

Sample Code

plugin.on('data', data => {
  client
    .callMethod(data)
    .then(result => {
      return plugin.pipe(data, result)
    })
    .catch(err => {
      plugin.logException(err)
    })
})

Reference Implementations

Listed below are some reference implementations of the Service Plugin API.

• Google Geocoding Service
• Dark Sky Service
• OpenWeatherMap Service

These are just some of the Service Plugins developed and open-sourced by Reekoh. You may visit our Gitlab Page for more information. Contributions are most welcome.