Converters 2.0 – Making Custom Programming Even Easier in Reekoh

 

January 10, 2019  |  By Andrei Hawke

Converters are a key building block of Reekoh solutions and allow customers and partners to define flexible
solutions on the fly.

 
Just like our other plugins, Converters are a drag-and-drop object that is used inline along the flow of data in a Pipeline. Converters can be thought of as a “Swiss Army Knife”, allowing for a range of functions such as:

  • Use of Custom Libraries
  • Custom Validations
  • Binary Conversion
  • Data Manipulation
  • Data Cleaning


sample pipeline

Figure 1: Typical Converter Placement in a Reekoh Pipeline
 
Reekoh has been hard at work improving not just the usability of converters, but also adding extra functionality to help customers solve problems even quicker (Reekoh is all about bringing speed and agility to Enterprise Data Integration).

 
Here are some of the recently added features in the latest version of Converters (2.0):

Ability to Break Up Arrays to Single Data Points

If you ingest a data point with a lot of readings (e.g. from an API call) it is often useful to break up these readings in to individual components. Customers can now do this by passing a JavaScript Array Object to the Converter and the Converter will automatically break these up in to individual readings (note: the JavaScript Array Object needs to be populated by Objects not readings).

For example:

{
    "device": "XDevice",
    "readings": [
        {
            "name": "Reading 1",
            "temp": 34,
            "humidity": 70
        },
        {
            "name": "Reading 2",
            "temp": 38,
            "humidity": 75
        },
        {
            "name": "Reading 3",
            "temp": 36,
            "humidity": 71
        }
    ]
}

Would emit the following readings:

{
    "name": "Reading 1",
    "temp": 34,
    "humidity": 70
}
{
    "name": "Reading 2",
    "temp": 38,
    "humidity": 75
}
{
    "name": "Reading 3",
    "temp": 36,
    "humidity": 71
}

While

[3,4,5,3,2]

Although a valid JavaScript array, will not emit any readings.
If we update the typical converter to code to resolve data.readings (an array) we can see the results

return Promise.resolve(data.readings)


converter code


converter logs-1

 

Programmable Cache for Each Converter

Each converter now comes with a cache that can be used to store values as needed. This allows programmers to create new solutions such as stitching data with multiple time points, preventing alarm floods (e.g if a high alarm has been raised don’t raise another) and many more.

There are 3 key components to working with the cache:
 
1. Including the state object in the converter exports method

exports.handle = function (data, logger, state) { }

 
2. Setting a State with a JSON String (recommended format):

let new_state_object = { "timestamp": Date.now(), "value": Math.floor(Math.random() * 200) + 1 }
    
state.setState(JSON.stringify(new_state_object))
    .then(() => {
        logger.log(`State Set to : ${new_state_object}`)
    })
    .catch((error) => {
        logger.log(error)
    })	

 
3. Retrieving a State (JSON String then Convert Back to Object):

state.getState()
    .then(current_state => {
        logger.log(`Current State: ${current_state}`)
        data.data_in_cache = JSON.parse(current_state)
    })
    .catch(error => {
        logger.log(error)
    })

 
The full code snippet is available at https://gitlab.com/reekoh/service-sales-engineering/code-snippets

You can verify the state is functioning as you expect by reviewing the logs:


converter logs-2


converter log details

 

Reekoh Converters Code Snippets

Do you ever get stuck on which XML parsing library is best? Or which Promise Library to use? Or What Binary Parsing library to use?

Reekoh has been collecting snippets to help customers to get started with NodeJS and Converter programming even quicker.

The snippet collection can be found on our Gitlab: https://gitlab.com/reekoh/service-sales-engineering/code-snippets

If you would like to see a new snippet contact us and we will be happy to create one.

 

Simplifying Syntax Related Troubleshooting

Syntax validation is an important part of ensuring the shipping of quality code. Reekoh uses JSHINT to lint code in converters to ensure customers have a seamless and friction-less experience with our converters.

We have reviewed our JSHINT validation rules and relaxed some of the enforcement to let you port your code to Reekoh even quicker.

As well as simplifying the linting validation we have also added visual feedback to speed up the identification of typical syntax issues (such as not closing braces).


converter editor lint

 

How to Migrate to Converters 2.0:

To ensure backward compatibility customers who have existing converters in Reekoh will remain on version 1.0 (original converters).

The process of upgrading to Converters 2.0 is as simple as selecting 2.0 from the Plugin Version and saving the pipeline again.


converter version

 
If you would like assistance with migrating to Converters 2.0 please reach out to our support team or your technical account contact.