Node-RED: nodes and common techniques

The nodes and common techniques described in this chapter will help you to start creating flows for an OL Connect application in Node-RED.

The typical flows that an OL Connect application may have are described separately; see Flows in an OL Connect application.

For the user documentation of Node-RED, please refer to Node-RED's website: nodered.org.

This chapter uses a startup flow for the examples. See also: OL Connect startup flow

Nodes used in OL Connect flows

In addition to the OL Connect nodes, these standard nodes will often be used in OL Connect applications:

  • The inject node triggers the flow. It can be setup in a way that it triggers the flow whenever it is deployed or when Node-RED is started (see OL Connect startup flow). It can also be used to inject the full path to a (sample) data file into a flow.

    Tip: Adding multiple inject nodes to your flow is a great way to test the flow with data files of different sizes.

  • The HTTP in node creates an HTTP end-point for creating web services.

  • Any flow that starts with an HTTP in node must have a path to an HTTP response node otherwise requests will eventually timeout.

  • The read file node loads a file. If the file is a JSON file, the result is a JSON string.

  • The write file node writes the content of msg.payload to a file.

  • The JSON node parses a JSON string and adds the keys with their values as properties to msg.payload.

  • The change node can initialize variables and change their value.

  • The function node executes JavaScript code. See https://nodered.org/docs/user-guide/writing-functions.

  • The debug node displays the content of the msg object, which is passed between nodes in a flow, in the debug message console.

    Tip: Add a debug node - one for each property of the msg object - after another node to verify that the properties are changed as expected.

  • The split node turns a single msg.payload consisting of an array into a series of messages, each of which has a payload containing one of the array's elements. Note that the Split node only works on msg.payload and not on its child objects.

    Tip: The join node can be used to continue a flow after iterations made with the split node are done.

  • The switch node can have multiple output channels and these channels can be linked back to a node on the primary/main branch downstream. The switch node allows messages to be routed to different branches of a flow by evaluating a set of rules for each message.

Reading a JSON file

In order to load a JSON file you can use a read file node. Set the Filename property to the full path.
Note that when Node-RED's project feature is used, the path is relative to the project location under Node-RED's user directory (%userprofile%/.node-red/).

Example

When triggered, a startup flow must read the manifest.json file.

  1. Add a read file node after the inject node that triggers the flow, and connect their ports.
  2. Double-click the read file node to view its properties.
  3. Paste or enter the full path to manifest.json in the Filename property. For example: C:\projects\project-a\resources\manifest.json, or, when using Node-RED's project feature: node-red\projects\project-a\manifest.json.
  4. You can change the Name of the node, for example into: Read manifest.
  5. Click Done.

Parsing a JSON string

When a JSON file is read, the result is a JSON string. In order to access its data, that string needs to be parsed to its JavaScript Object representation. Node-RED provides the JSON node to do this conversion.
The parsed data is written to the payload property of the msg object, which is passed on to the next node. Keys in the JSON become properties of the payload.

Example

After reading the manifest.json file using a read file node, a startup flow must parse the JSON string in order to add the keys and values to msg.payload. The manifest.json file has the following content:

{

	"email": "Laura from OL Acme <laura@ol-acme.com>",

	"someApi": "http://localhost/myendpoint",

	"workspace": "C:\\workspace",

	"resources": [

		"olsg-invoice.OL-template",

		"olsg-invoice-XML.OL-datamapper"
  ]

}

  1. Add a JSON node after the read file node. Make sure the JSON node is connected to the output port of the read file node.

  2. Add a debug node and connect the JSON node to the input port of that debug node so that the result can be viewed in the debug message console, once the flow is deployed.

After the JSON file is parsed, the msg object will have the following properties: msg.payload.email, msg.payload.someApi, msg.payload.workspace and msg.payload.resources.

Using variables

There are various ways to set and get the values of (global and other) variables, for example:

  • Via the change node. A 'Set' rule can set the value of one variable to a hard-coded value or to the value of another variable (e.g. 'Set' global.email to msg.email object).

  • Via the function node, using JavaScript. The node has access to the msg object as well as to the different contexts: context (i.e. the node's local context), , flow and global.

The Context sidebar in the editor of Node-RED displays the contents of the context data store and allows to view the stored variables. The view consists of three sections, one for each context: node, flow and global.

Variables stored in the global context of Node-RED are visible to all nodes, in all flows, on all tabs. Through these variables, information is shared between nodes without using the messages that pass through a flow.

Example

After parsing a JSON string, a startup flow must initialize global variables to the values of properties of msg.payload.

  1. Insert a change node after the JSON node (wire the input port and the output port).

  2. Double-click the change node to view its properties.

  3. Create a rule for each of the values. For example:

    'Set': global.email

    To: msg.payload.email

  4. Click Done.

  5. Add a debug node and connect the change node to the input port of that debug node so that the result can be viewed in the debug message console.

Setting and moving msg properties

There are various ways to set and move values of properties in the msg object.

  • Via the change node. Select 'Set' to set a value; select 'Move' in order to move a value from one property to another property.

  • Via the function node. The value of a property can be set or replaced using JavaScript.

Example

After reading and parsing a manifest.json file, a startup flow needs to move the names of some OL Connect resources from msg.payload.resources to msg.payload

  1. Add a change node to the flow.

  2. Create a rule to 'Move' msg.payload.resources to msg.payload.

Iterating over items in an array

If items in an array need to be passed on individually, the flow will need to iterate over the items. This kind of loop is handled by Node-RED's split node. The split node turns a single msg.payload, consisting of an array, into a series of messages, each of which has a payload containing one of the array's elements.

Note that the split node only works on msg.payload and not on its child objects.

Example

A startup flow needs to iterate over the array in msg.payload that contains the names of OL Connect resources.

  1. Insert a split node into the flow.

  2. Add a debug node to verify that Node-RED creates a new message for each resource name.

Concatenating strings

To concatenate two strings in different variables, one could use a function node and script it, or use a change node.

Example

A startup flow needs to upload an OL Connect resource to the OL Connect server, but the resource name in msg.payload lacks the path. The path is stored in msg.resourceFolder. To construct the full path and pass it via msg.fileName, the flow can use a change node.

  1. Add a change node and a file upload node.

  2. Double-click the change node and create a rule to 'Set' msg.fileName to msg.resourceFolder & payload. The latter is a JSONata expression.