The message is passed in as an object called
msg. By convention it will
msg.payload property containing the body of the message.
Other nodes may attach their own properties to the message, and they should be described in their documentation.
The code entered into the Function node represents the body of the function. The most simple function simply returns the message exactly as-is:
If the function returns
null, then no message is passed on and the flow ends.
The returned message object does not need to be same object as was passed in; the function can construct a completely new object before returning it. For example:
msg.resproperties to be preserved end-to-end. In general, function nodes should return the message object they were passed having made any changes to its properties.
The function edit dialog allows the number of outputs to be changed. If there is more than one output, an array of messages can be returned by the function to send to the outputs.
This makes it easy to write a function that sends the message to different
outputs depending on some condition. For example, this function would send
anything on topic
banana to the second output rather than the first:
The following example passes the original message as-is on the first output and a message containing the payload length is passed to the second output:
A function can return multiple messages on an output by returning an array of messages within the returned array. When multiple messages are returned for an output, subsequent nodes will receive the messages one at a time in the order they were returned.
In the following example,
msg3 will be sent to the first output.
msg4 will be sent to the second output.
The following example splits the received payload into individual words and returns a message for each of the words.
If the function needs to perform an asynchronous action before sending a message it cannot return the message at the end of the function.
Instead, it must make use of the
node.send() function, passing in the message(s)
to be sent. For example:
If you do use asynchronous callback code in your functions then you may need to
tidy up any outstanding requests, or close any connections, whenever the flow gets
re-deployed. You can do this by adding a
close event handler.
If a node needs to log something to the console, it can use one of the follow functions:
error messages also get sent to the flow editor debug tab.
For finer grained logging,
node.debug() are also available.
If there is no logger configured to capture those levels, they will not be seen.
If the function encounters an error that should halt the current flow, it should
return nothing. To trigger a Catch node on the same tab, the function should call
node.error with the original message as a second argument:
Aside from the
msg object, the function can also store data between invocations
The following example maintains a count of how many times the function has been run:
By default, the context data is not persisted across restarts of Node-RED.
contextwas to access it directly:
var count = context.count;This method is still supported, but deprecated in favour of the
context.setfunctions. This is in anticipation of being able to persist the context data in a future release.
Just as the
context object is local to the node,
there is also a flow-level context that is shared by all nodes, not just Function
nodes, on a given tab. It is accessed via the
There is also a global context available that is shared by, and accessible to all nodes. For example to make the variable foo available globally across the canvas:
And can then be read using .get
The global context can also be pre-populated with objects when Node-RED starts. This
is defined in the main settings.js file under the
context.global.foo = "bar"; var osModule = context.global.osModule;This method is still supported, but deprecated in favour of the
global.setfunctions. This is in anticipation of being able to persist the context data in a future release.
The function node can also provide it’s own status decoration in the same way
that other nodes can. To set the status, call the
For details of the accepted parameters see the Node Status documentation
Any status updates can then also be caught by the Status node.
Additional node modules cannot be loaded directly within a Function node. They must
be loaded in your settings.js file and added to the
For example, the built-in
os module can be made available to all functions by
adding the following to your settings.js file.
at which point, the module can be referenced within a function as
Modules loaded from your settings file must be installed in the same directory as
the settings file. For most users that will be the default user directory -
cd ~/.node-red npm install name_of_3rd_party_module
The following objects are available within the Function node.
node.id: the id of the Function node - added in 0.19
node.name: the name of the Function node - added in 0.19
node.log(..): log a message
node.warn(..): log a warning message
node.error(..): log an error message
node.debug(..): log a debug message
node.trace(..): log a trace message
node.on(..): register an event handler
node.status(..): update the node status
node.send(..): send a message
context.get(..): get a node-scoped context property
context.set(..): set a node-scoped context property
context.keys(..): return a list of all node-scoped context property keys
context.flow: same as
context.global: same as
flow.get(..): get a flow-scoped context property
flow.set(..): set a flow-scoped context property
flow.keys(..): return a list of all flow-scoped context property keys
global.get(..): get a global-scoped context property
global.set(..): set a global-scoped context property
global.keys(..): return a list of all global-scoped context property keys
RED.util.cloneMessage(..): safely clones a message object so it can be reused
The Function node also makes the following modules and functions available:
Buffer- the Node.js
console- the Node.js
node.logis the preferred method of logging)
util- the Node.js
Note: the function node automatically clears any outstanding timeouts or interval timers whenever it is stopped or re-deployed.