function

Overview

The messages are passed in as a JavaScript object called msg.

By convention it will have a msg.payload property containing the body of the message.

The function is expected to return a message object (or multiple message objects), but can choose to return nothing in order to halt a flow.

The On Start tab contains code that will be run whenever the node is started. The On Stop tab contains code that will be run when the node is stopped.

If the On Start code returns a Promise object, the node will not start handling messages until the promise is resolved.

See the online documentation for more information on writing functions.

Sending Messages

The function can either return the messages it wants to pass on to the next nodes in the flow, or can call node.send(messages).

It can return/send:

• a single message object - passed to nodes connected to the first output
• an array of message objects - passed to nodes connected to the corresponding outputs

Note: The setup code is executed during the initialization of nodes. Therefore, if node.send is called in the setup tab, subsequent nodes may not be able to receive the message.

If any element of the array is itself an array of messages, multiple messages are sent to the corresponding output.

If null is returned, either by itself or as an element of the array, no message is passed on.

Logging and Error Handling

To log any information, or report an error, the following functions are available:

• node.log("Log message")
• node.warn("Warning")
• node.error("Error")

The Catch node can also be used to handle errors. To invoke a Catch node, pass msg as a second argument to node.error:

node.error("Error", msg);

Accessing Node Information

The following properties are available to access information about the node:

• node.id - id of the node
• node.name - name of the node
• node.outputCount - number of node outputs

Using Environment Variables

Environment variables can be accessed using env.get("MY_ENV_VAR").

Common Use Cases

Data Transformation

Transform incoming data:

// Transform the payload
msg.payload = {
  original: msg.payload,
  processed: true,
  timestamp: new Date().toISOString(),
};

return msg;

Conditional Processing

Implement conditional logic:

if (msg.payload.status === "active") {
  msg.payload.action = "process";
  return msg;
} else {
  // Don't send message for inactive items
  return null;
}

Multiple Outputs

Send messages to different outputs:

if (msg.payload.type === "urgent") {
  return [msg, msg]; // Send to outputs 1 and 2
} else {
  return [null, msg]; // Send only to output 2
}

Context Management

Work with flow and global context:

// Read from context
var count = flow.get("messageCount") || 0;

// Increment and store
flow.set("messageCount", count + 1);

// Add to message
msg.payload.count = count + 1;

return msg;

Error Handling

Implement custom error handling:

try {
  // Process the message
  msg.payload.result = processData(msg.payload);
  return msg;
} catch (error) {
  node.error("Processing failed: " + error.message, msg);
  return null;
}

Tips

• Use meaningful variable names and add comments for complex logic
• Handle errors gracefully to prevent flow failures
• Use context to store state between message processing
• Return null to stop message flow when appropriate
• Use multiple outputs for conditional routing
• Test your functions thoroughly with different input data
• Use the debug panel to inspect message contents

Notes

• Functions run in a sandboxed environment for security
• The msg object is passed by reference, so modifications affect the original
• Functions can access the full message object for your flow
• Use node.send() for asynchronous operations
• The function block is one of the most powerful and flexible blocks available

Related Blocks

• change - For simple property modifications
• template - For text formatting
• switch - For conditional routing