Function Node

The Function Node allows execution of arbitrary, user-defined JavaScript against a workflow payload.

Configuration

The Function Node configuration takes two inputs.

Function Scope

Optionally, you may provide a payload path to serve as the value of the payload variable in the function script. If a path is not provided, the entire workflow payload will act as the payload variable value. By specifying a path, you can reduce the size of the data you are working with to only that which you need, leading to better workflow performance and less risk of error. In the above example, the Function Node only has access to the data path on the workflow’s payload.

For Edge Workflows, the ability to provide a Function Scope Path is only available in GEA version 1.30.0 and higher.

Code

THe function provided is the script to execute against your payload. The provided script must be valid JavaScript; the web interface provides a code editor with syntax highlighting to make this easier.

In the above example, the Function Node is averaging the values of an array of data, and storing that average in the payload field average, which will be accessible via data.average to the rest of the workflow.

Considerations

When writing your Function Node script, there are a few points to consider:

Buffers

The Buffer Object is available in the Function Node. The Buffer class is specifically designed to handle and work with raw binary data.

For example, for a hex string on the payload that represents the float 3.14159 at data.hex, it can be converted back to the float using the following function:

var hex = payload.data.hex;
var b = Buffer.from(hex, 'hex');
var value = b.readFloatLE(0);
payload.data.value = value; // 3.14159

The float value can now be accessed in the following nodes on the data.value payload path.

Console Output

JavaScript console outputs can be used to provide feedback on code execution, debug errors, and aid in the development process. The console outputs can be categorized based on their level of importance, with each console method corresponding to a particular debug level in the debug log as described below.

The above console methods will output to the debug log only if their corresponding debug level is configured to be displayed.

NOTE: The workflow engine debug feature described in this section is only applicable for GEA version 1.38.0 or higher. In other GEA versions, all console methods will have a debug level of verbose.

Syntax

ES5 and ES6 syntax are both valid. Other ECMAScript specifications are not supported.

Asynchronous Operations

• Asynchronous operations and events (such as Promises, setTimeout, and setInterval) are not valid. All code must execute synchronously.

Third-Party Modules

Third-party libraries (such as those published on npmjs.com and referenced through import or require) are only supported in Edge Workflows. In those cases, it is up to you to store the library on disk and reference them by the correct path in your Function Node. For example …

const _ = require('/data/scripts/lodash.min.js');

Performance

For security purposes, each time a Function Node is invoked, a discrete sandbox is created in which the code executes and modifies the payload before returning to the outer workflow. The construction and deconstruction of this sandbox introduces a fixed time cost. This has several implications:

• A Function Node will almost always be slower than a native node when running an equivalent task.
• We advise against using Function Nodes in Loops when possible.

Additionally, there is a limit on the number of concurrent Function Nodes that can be running in an application, which may lead to delays in workflow completion.

For more information on best practices for using Function Nodes, please see our Building Performant Workflows reference guide.

Payload Modification

If you provided a Function Scope Path, the data at the provided path will be available at the variable payload; otherwise the payload variable will be the entire current payload of the workflow. There are two ways a Function Node can modify this value.

Mutating the Payload

In most cases, users opt to modify properties on the incoming payload. For example, given the following script:

payload.data.newItem = 'Something Special';
payload.data.oldNumber = payload.data.oldNumber + 1;

And an example payload of:

{
  ...
  "data": {
    "oldNumber": 5
  }
  ...
}

The payload after the execution of that Function Node would be:

{
  ...
  "data": {
    "newItem": "Something Special",
    "oldNumber": 6
  }
  ...
}

Returning a New Payload

Alternatively, you may return any value within the Function Node. If a Function Scope Path has been provided, this value will serve as the new value at that path; otherwise that value will then serve as the full workflow payload from that point forward.

return { value: 'Total Replacement' }

If that were the entire contents of a Function Node with no Function Scope Path provided, the payload after the execution of the Function Node would always be the object:

{ "value": "Total Replacement" }

Note: If a return statement is used, but no value is returned, the value of the payload variable at the end of the node’s execution is used as the new payload.