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 function must always return a msg object. Returning a number or string will result in an error.
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. It takes the same arrangement of messages as that can be returned, as
described in the previous sections.
Since Node-RED 1.0
The Function node will clone every message object you pass to
ensure there is no unintended modification of message objects that get reused
in the function. Before Node-RED 1.0, the Function node would not clone the
first message passed to
node.send, but would clone the rest.
The Function can request the runtime to not clone the first message passed to
node.send by passing in
false as a second argument to the function. It would
do this is the message contains something that is not otherwise cloneable, or for
performance reasons to minimise the overhead of sending messages:
Since Node-RED 1.0
If a Function node does asynchronous work with a message, the runtime will not automatically know when it has finished handling the message.
To help it do so, the Function node should call
node.done() at the appropriate
time. This will allow the runtime to properly track messages through the system.
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 in the context store.
More information about Context within Node-RED is available here.
In the Function node there are three predefined variables that can be used to access context:
context- the node’s local context
flow- the flow scope context
global- the global scope context
The following examples use
flow context, but apply equally well to
There are two modes for accessing context; either synchronous or asynchronous. The built-in context stores provide both modes. Some stores may only provide asynchronous access and will throw an error if they are accessed synchronously.
To get a value from context:
To set a value:
The following example maintains a count of how many times the function has been run:
Since Node-RED 0.19, it is also possible to get or set multiple values in one go:
In this case, any missing values are set to
If the context store requires asynchronous access, the
require an extra callback parameter.
The first argument passes to the callback,
err, is only set if an error
occurred when accessing context.
The asynchronous version of the count example becomes:
With 0.19 it is possible to configure multiple context stores. For example, both
file based store could be used.
set context functions accept an optional parameter to identify the store
The global context can be pre-populated with objects when Node-RED starts. This
is defined in the main settings.js file under the
This can be used to load additional modules within the Function node.
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
node.done(..): finish with 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
get(..): get an environment variable
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.