This brief tutorial will show you how to invoke a Building Insights API from a Node-RED application.

Prerequisites

This tutorial assumes that you are familiar with IBM Cloud and how to create a Node-RED starter app.

Also, you will need the username and password that is provided in your Building Insights Welcome Letter.

Estimated time

Completing this tutorial should take about 30 minutes.

Steps

1

Import the demo flow into Node-RED

Let’s work with the demo flow that I’ve provided in a JSON file. Open the JSON file, and copy the contents to a clipboard.

In your Node-RED editor, from the Node-RED menu, choose Import > Clipboard, and then paste the contents of the JSON file into the dialog.

2

Authenticate with the Building Insights Login API

All of the Building Insights APIs are secured via a bearer token. Therefore, the first step is to authenticate with the Building Insights login API, normally found here:

https://{{domain}}-agg.{{IBM Cloud domain}}/api/v1/user/activity/login

The domain and IBM Cloud domain were provided to you in your Welcome Letter. You can find more information about this login REST API in the TRIRIGA documentation.

This API is invoked using a POST method and takes in an application/json body in the following format:

{
  "username": "username",
  "password": "password"
}

You need to specify the username and password from your Welcome Letter.

The following Node-RED flow demonstrates how to get the bearer token:

Node-RED flow for how to get bearer token

Open and edit the prepareCall node. Enter the login URL (line 10), the username (line 19), and the password (line 20), and then click Done.

Node-RED prepareCall node

If the values are correct, click the Deploy button to send the changes to the server. You can test this authentication now by clicking the inject button on the getToken node. The flow should output a valid bearer token to the debug window on the right (an error would also output to the debug window on the noToken node):

Node-RED flow showing testing bearer token

The setToken function adds the Bearer portion to the beginning of the token.

Node-RED setToken function

It also creates a flow variable in the context area, which allows for re-use of the token by any other nodes in the same flow:

Node-RED flow showing setToken function

3

Invoking the Building Insights Data API

After successfully retrieving a bearer token, we can use it on subsequent API calls to retrieve the Building Insights data.
The following flow retrieves data using the token:

Node-RED flow for invoking data api

Open and edit the prepareCall node. Enter the aggregator URL (line 6) and the API to use (line 7), and then click Done:

Node-RED prepareCall node in data api flow

As the example above shows, the bearer token is fetched from the flow (line 12) prior to invoking the call. If multiple flows will use the same token, it would be better to place the token in the global context instead of the flow context (using global.set in setToken function).

After updating this function, click the Deploy button to send the changes to the server. After that is complete, you can invoke the getData node:

Node-RED getData node in data api flow

The API is invoked and the results are placed in the debug window.

Summary

After using this tutorial, you should have good understanding of how to retrieve a Building Insights bearer token using NodeRED. You should also have a good understanding of storing the token in a global context and re-using the token for invoking Building Insights authenticated API’s.