In this article I’m going to show how you can get your Node-RED flows talking to your Orchestrate database. For novices to Node-RED and using it to consume web APIs, you can also view this as a model for that kind of work in future. First, allow me to introduce the two main technologies featured.

Node-RED has been a revelation in the hacker and maker space. A product of IBM’s labs (and spearheaded by some very smart people), Node-RED gives the average person a powerful way to make complicated things happen, using the power of flow-based programming and an easy-to-use GUI. People are using it to do all sorts of interesting things and if you haven’t looked at it already, you really should!

Orchestrate is a new breed of database as a service. All your database interactions are done through a nice API and it functions as a NoSQL JSON document storage base with some powerful search, graphing and event capability. Those of you out there who have used something like MongoDB will feel very at home, and may even prefer the query syntax, as I do. As you get up to a million calls per month free of charge, you’ve no excuse not to give it a try.

To start with, you’ll need an Orchestrate account and a Node-RED instance.

Welcome to your Orchestrate dashboard

Welcome to your Orchestrate dashboard

There are great docs for getting Node-RED going at their site, so hit them up to get your Node-RED instance up and running locally (or get a free IBM Bluemix account and spin one up there) but I’ll give you a quick Orchestrate intro, pointing out the bits you’ll need.

You can easily grab an account at orchestrate.io. Once you’re in, you’ll need to hit the “+ New Application” button as pictured. I’ve already done that and called my example application rndlabs-example. You’ll want to call it something different, as these have to be unique. Once you’ve got an app created, add a collection to it (I called mine “temps”) and grab the API key – you’ll need this later.

Click to reveal that API key and save it for later. You can, of course, always get it from here at a later date.

Click to reveal that API key and save it for later. You can, of course, always get it from here at a later date.

At this point I would recommend reading through the handily linked-to docs in order to familiarise yourself with the basic structure of the Orchestrate API, and also clicking in to your fledgling collection and checking out the nice frontend for querying your data. In itself it will help you understand how to form queries. The structure for PUTs –

is particularly important.

Now let’s head over to our Node-RED instance and get this party started.

A high level look at our simple flow.

A high level look at our simple flow.

As you can see, our flow is simple – a mere four nodes (and the end one, “debug” is largely optional). A quick overview may be in order:

  • inject: This node kicks things off by passing a unix timestamp through to its next of kin node. It’s a basic way to test.
  • orchestratify: This node represents the meat of our work, and contains a Javascript function to format our data payload for the API call to Orchestrate.
  • http request: Here is where the actual call is made, using the message passed to it from the orchestratify function node.
  • debug: Outputs what is returned from the http request node, allowing us to make sure that the call went off unmolested and error-free.

As the bulk of the work is in the function node “orchestratify”, let’s take a look at what’s going on under the hood.

First of all, there’s nothing special about the name. You could call the node whatever you like – what matters is the actual function inside.

When you double click (or left and then right click as I have to do), you’ll see this interface:

The innards of the orchestratify node.

The innards of the orchestratify node.

And here is the code in a nicely copy-and-pastable form.

The purpose of the flow, for this example, is to track the temperature of a device – in this case with device ID 1 – over time.

The timestamp is easily read from msg.payload. Each function node is passed a “msg” object from the node ahead of it in the flow. The msg.payload, in this case, contains the timestamp as generated by the “inject” node preceding it. We grab this for the data we’ll send to orchestrate. Note that this is mainly just to demonstrate the msg.payload concept – Orchestrate automatically timestamps all the entries anyway. This could, of course, be useful for tracking other times if the calls to the API were delayed.

I set a deviceId which is in this case entirely arbitrary but could be coming in in the payload from a more complicated source (as would be happening in a proper Node-RED-built API).

I create a random temp(erature) between 20 and 30 and then set about turning the msg object to my own purposes.

The msg.url property is important as it will be read by the HTTP request node following this one. It contains a URL with the Orchestrate PUT form as I highlighted earlier. If your collection is called something other than temps or you want to use a different property to create a unique key, that’s totally fine. Change as necessary.

msg.headers is also a necessary property for the HTTP request node.

Into the payload section (again, a necessity), we place the components of the object we want to send to Orchestrate. This is our JSON document, analogous to a row in an SQL database, for those coming from that background.

Then we return that object to be read by the HTTP request node. Let’s see what happens there.

Here's what's going on in the HTTP request node.

Here’s what’s going on in the HTTP request node.

This is pretty straighforward. We change the method of the node to be PUT, ensure that basic authentication is used and then input the API key we took down earlier (or can now grab from the application dashboard on Orchestrate) into the Username field of the popup. This node will read the URL, headers and payload parts of the incoming msg object in order to work out the rest. Again, you can name this node whatever you’d like. This is more important in larger flows.

To check everything is working, we throw a debug node on the end of the chain. Then we can hit the Deploy button to save our flow (and activate it) and, finally, check it all works by crossing our fingers and clicking the button on the inject node.

All going well, in the debug tab on the right you will see something like the following:

Our beautiful (?) Orchestrate success message.

Our beautiful (?) Orchestrate success message.

When you see statusCode of 201, you can breathe a sigh of relief and pat yourself on the back. Bonus points for doing both at the same time.

If you want to see the fruits of your labour you can jump back over to your Orchestrate dashboard and check on your example collection. Click the red arrow next to the example GET request to view all the entries in your collection.

For me I have just the one, the successful result of our little experiment.

It is ALIVE!

It is ALIVE!

Now that you know how, you can incorporate Orchestrate data storage (and retrieval – perhaps the topic of a future post) into your Node-RED IoT flows and have your devices storing lots of useful date for you to track.

Good luck!

Update

I decided it would be nice if this all existed as a Node-RED module, installable from NPM, so here it is.

WordPress Backup