Script

Overview

Script runs a block of custom JavaScript against your flow's data. Read and write flow variables with real code, instead of chaining several Change Data, Regex, or Look Up stages together for the same logic.

* Example flow demonstrating how Script calculates the tax and total for an order in a single step and passes the results to the flow response.

Where to find it: Expert in the stage library.

When to Use

• Combine several data transformations into one step instead of a long chain of stages
• Loop over a list stored in a variable and build a derived value (sums, joins, filtered lists)
• Reshape the structure of a JSON object before passing it downstream
• Any logic that's awkward with the built-in stages but simple to express in JavaScript

Configuration

Required Fields

Using functions in these fields: Any value field above accepts @ functions, for example @NowSecond for the current time or @calc(...) for a calculation. 

See Flows Functions for the full list.

Exit Points

There is no Fail exit, only Pass or Error.

How It Works

1. Variables are filled in first. Any {{variable}} in your code is replaced with the flow's value before the script runs. This is a straight text substitution, so flow['greeting'] = `Hello {{name}}`; becomes flow['greeting'] = `Hello Liam`; before the code is read.
2. Your flow data is available as an object called flow. Every variable in your flow becomes a property on flow. Values that are valid JSON are turned into real arrays and objects automatically, so you can work with them directly. Anything else comes through as plain text.
3. Whatever you write onto flow is saved back to your flow when the script finishes. Any property on flow at that point, whether it was there before or you added it, becomes a flow variable. Arrays and objects are saved as JSON text automatically.
4. There's no return. The only way to get data out of a script is to assign it onto flow. The stage always takes the Pass exit on success, no matter what the last line evaluates to.

Reserved Variables

A small set of system variables can be read from your script but cannot be overwritten. You can copy their values into your own variables, but assigning to them has no effect. The flow keeps its original value.

The reserved names are OperatorID, flow.instance, flowtime, stages, lastresult, success, Started, and any variable starting with connection.

What Scripts Can and Can't Do

Examples

1. Combine fields into a summary

flow['summary'] = 'Name: ' + flow['name'] + ', Age: ' + flow['age'];

With name = "Liam" and age = "24", this sets summary to "Name: Liam, Age: 24".

2. Do maths across variables

var amount = parseFloat(flow['order.amount']);
    flow['order.tax'] = String(amount * 0.2);
    flow['order.total'] = String(amount * 1.2);

With order.amount = "100", this sets order.tax = "20" and order.total = "120".

3. Loop over a list stored in a variable

var names = [];
    flow['customers'].forEach(function(c) {
      names.push(c.name + ' (age ' + c.age + ')');
    });
    flow['customer.summary'] = names.join(', ');
    flow['customer.count'] = String(flow['customers'].length);

customers was saved as JSON text, so it comes through as a real list you can loop over directly.

4. Change an object and save it back

flow['user'].name = 'Updated';

user is available as an object, so you can change a property on it directly. The updated value is saved back to your flow as JSON text automatically when the script finishes.

Edge Cases

• A script that never writes to flow: Leaves your flow data exactly as it was
• Reading a reserved variable: Always works; only writing to it is ignored
• Syntax errors, runtime errors, and timeouts: All behave the same way. The stage takes the Error exit, and the error message is recorded on the stage
• Ordinary text values: Come through as plain text, not as objects. Only values that are valid JSON are turned into arrays or objects

Best Practices

• ✓ Use Script to replace a long chain of stages when the logic is genuinely easier in code
• ✓ Always assign your results onto flow['key']; that's the only way to get data out
• ✓ Keep scripts short and quick; the 10-second limit is generous but not unlimited

Common Mistakes

Related Stages

• Change Data: Simpler single-field transforms without writing code
• Look Up: Static key-to-value mapping, no code required