How to use Node-RED client library to interact with onesait Platform?

Owned by DevPortal Editor (Unlicensed)
Last updated: 10/03/22 by Onesait Platform
7 min read

Introduction

Node-RED is nowadays a very popular programming tool, allowing developers to create programs visually. From a very wide palette of nodes, developers can create flows by wiring them together. Developers can also create their own nodes to fulfill their needs and then share them with the community via NPM. Developing PoCs using a flow engine like Node-RED is easy and quick.

onesait Platform already provides a flow engine within its Control Panel, with a straightforward connection to the data stored on the platform. This page presents the client library to interact with onesait Platform from a Node-RED instance running in a client device (another system, a Raspberry Pi ...)

Nodes description

The client package has six user nodes featuring different operations over the platform, plus one config node dealing with the connection details. Let's describe each node in detail: 

  •  

    • onesait-platform-insert: this node inserts data in an ontology. The following parameters are required:

    • onesait-platform-delete: this node deletes data from an ontology according to a query, or by RTDB ID. The following parameters are required:

      • Ontology: name of the ontology. To create an ontology, please go to https://lab.onesaitplatform.com/controlpanel/ontologies/list

      • Delete Type: the type may be by query-based or by Id.

      • Query/Id: query or id to be deleted, depending on the chosen type.

      • Query Type: SQL or NATIVE (MongoDB for CloudLab deployment).

    • onesait-platform-query: this node executes a query on an ontology. The following parameters are required:

    • onesait-platform-update: this node updates data in an ontology. The following parameters are required:

      • Ontology: name of the ontology. To create an ontology, please go to https://lab.onesaitplatform.com/controlpanel/ontologies/list

      • Update Type: type, may be by query-based or by Id.

      • Id: instance id to be updated.

      • Query: query; its result will be updated.

      • Query Type: SQL or NATIVE (MongoDB for CloudLab deployment)

    • onesait-platform-leave: this node closes the current session with the platform.

    • onesait-platform-subscribe: this node subscribes to any interaction with the selected ontology. The following parameters are required:

    • onesait-platform-connection-config: configuration nodes are globally scoped by default. This means that the state will be shared between flows. This node represents a shared connection to a remote system. In that instance, the config node is responsible for creating the connection (MQTT) and making it available to the nodes that use the config node. A REST interface is also a possibility to connect to the platform. The following parameters are required to define the connection:

      • IoTClient: name of the digital client.

    •  

      • Instance: name of the instance of the digital client.

      • Token: any token associated to the digital client.

      • Renovate session every: minutes elapsed, after which the connection will be renewed. The default value is 5 minutes

      • Protocol: protocol that will be used in the connection.  REST and  MQTT values can be chosen. Some specific parameters have to be filled for each case:

        • MQTT:

          • IP: IP of the platform server.

          • Port: Port of the MQTT connection to the platform.

          • Enable SSL/TLS security: Enable the check box to select SSL/TLS connection.

          • Certificate: If the previous check is selected, a certificate will be needed.

        • REST:

          • Endpoint: adress of the server where the platform el hosted. If https protocol is user, SSL/TLS sill be activated automatically.

          • Enable SSL/TLS security: If enabled, some extra SSL/TLS configuration will apear. It is not required even if https protocol is used.



Installation process

Firstly, you need to install Node.js from the official Node.js home page. Once installed, you may test your setup by opening a command prompt and running these commands: 

  • node --version

  • npm --version

At this point, Node.js should be installed and the versions would be appearing on the command prompt. The next step is installing Node-RED. To do so, run this command:

  • npm install -g --unsafe-perm node-red

When finished, you should be able to run Node-RED by running the command node-red on your prompt of choice. This version has already a good chunk of usable nodes that you can test at http://localhost:1880

The last step is installing onesait Platform Node-RED client is to run this command:

  • npm install node-red-contrib-onesait-platform

You might also install the client nodes from the Node-RED web interface from the right-hand side command menu→Manage palette, and then look for onesait:

At the end, it is necessary to restart Node-RED, and then the onesait nodes should appear as part of your palette.



Using the nodes from the example

There is an example flow available online to accelerate your learning curve when using this client library. It is available at https://flows.nodered.org/flow/989c8da7c08465f132882f24740c835f 

Once imported, your flow should look like this:

Even though this looks kind of messy, it is a simple flow to showcase all the capabilities from the nodes. This example is working out of the box since it has valid credentials from a demo user created for this example on our CloudLab instance. Let's dive into the several blocks and explaining them in detail:

CONNECTION-CONFIG

For the connection config node, it is embedded in the rest of the nodes as the server configuration property. Here you can see the values for one of the nodes in the example, using a REST interface to communicate with the platform.

QUERY

These two branches are performing an on-demand QUERY over onesait Platform data. All of our nodes have the option to input the node variables either manually or using an input message.

Let's focus on the first branch, using the input message flavor. This node requires some fields to be present in the incoming message, as presented in the Nodes description. Thus, the Parse node looks like this:

 

When clicking on the timestamp node, Node-RED triggers the query defined inside the Parse node, and then the Debug node shows the result from the query operation. The output is an array of JSON objects with the ontology instances matching the query criteria.

INSERT & DELETE

This block combines two nodes, Insert and Delete:

  • To Insert an instance to the platform, the pattern is similar to the one used in the Query example. This time, instead of the query, you need to pass the instance to be inserted into the platform (msg.payload), and the target ontology (msg.ontology):

  • The output from an insertion is the database ID assigned to the instance:         



  • There are two ways to Delete an instance in the platform:

    • By ID: this way deletes just the selected document under the input ID. This behavior is simulated in the top branch from this block. Firstly, there is an insertion with an associated returned ID, and then a deletion of that ID. The output of the Delete node is the number of deleted records in the database. The output from the first branch should look like this:

 

  •  

    • By Query: This option deletes records matching an input query. The third branch from this block performs this deletion by query:

      



UPDATE

The Update node is very similar to the Delete node since it is possible, once more, to perform the operation by ID or Query:

  • By ID: similar setup to the one used by the Delete node. The input msg contains the ID to be deleted (msg.id), the new and complete instance that will update the previous one (msg.query) and the ontology (msg.ontology). The output looks like this now:

 

  • By Query: it is also possible to Update the records matching an input query. The UpdateByQuery node contains the update Query (msg.query), and the query type (msg.queryType). The output tells the user how many records were updated.

SUBSCRIBE

The subscribe option works only with MQTT connection, thus you must configure this feature on your server (connection-config) node. The flow is easy, the input message must contain the ontology that the user will subscribe to. After triggering the command, the platform returns a subscription ID and the current subscriptions to the ontology. Then, the user will get notified of any operation over the ontology while the subscription is alive with a SSAPBodyIndicationMessage.

               

LEAVE

This flow just closes the current session and clears the user's session key.