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 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 onmsg.payload
and not on its child objects. -
The switch node can have multiple output channels and these channels can be linked back to a node on the primary/main branch down stream. 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.
- Add a read file node after the inject node that triggers the flow, and connect their ports.
- Double-click the read file node to view its properties.
- 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
. - You can change the Name of the node, for example into: Read manifest.
- 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"
]
}
-
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.
-
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
tomsg.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
andglobal
.
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
.
-
Insert a change node after the JSON node (wire the input port and the output port).
-
Double-click the change node to view its properties.
-
Create a rule for each of the values. For example:
'Set':
global.email
To:
msg.payload.email
-
Click Done.
-
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
-
Add a change node to the flow.
-
Create a rule to 'Move'
msg.payload.resources
tomsg.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.
-
Insert a split node into the flow.
-
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.
-
Add a change node and a file upload node.
-
Double-click the change node and create a rule to 'Set'
msg.fileName
tomsg.resourceFolder & payload
. The latter is a JSONata expression.