Workflow data

Data is passed between connectors as JSON, and can be used as parameters using expressions.

Most connectors produce output data after they are executed. This data is typically in the form of JSON, and can be viewed after a connector has executed by clicking on a connector to view its settings in a dialog box, then clicking on the arrow on the right side of the dialog box.

Example connector that has been executed by clicking the "Execute Connector" button. The output can be viewed by clicking the arrow on the right side of the dialog box.

Many connectors have parameters that specify the behavior of the connector, which can be viewed in a dialog box by double-clicking the connector. These parameters can be hardcoded by typing in the values in the given text box, or they can be dynamically set based on input data.

Setting dynamic parameters

Parameters that can be dynamically set have a gear icon to the right of the corresponding text box. Clicking on the gear icon will open a dropdown with options for how to set the value of the parameter, which are:

• Data from Last Connector: If the input of the current connector is connected to another connector that has been executed, you can use the UI to select one of the columns in the input data as the source of the value for that parameter in the current connector.

• Add Expression: For more advanced usages, you can enter an expression to set the value of the parameter. You can do this by either typing an expression value, or selecting one of the values from the input data in the left-side bar of the expression dialog box (if the input connector has been executed first).

To edit an existing expression, click the gear icon and select "Edit Expression". If you have previously used "Data from Last Connector", selecting the "Edit Expression" option will convert it into an editable expression.

Example of the drop-down that is opened by clicking the gear icon to the right of a connector's parameter.

Expression syntax

By default, text that is typed into an expression is interpreted literally. In order to mark a section of text that should be based on input data, insert double curly brackets ({{...}}), and within the curly brackets, enter the name of the field in the input data to use. Fields from the input data are referenced using the prefix $json.

Fields can be referred to using the same syntax as in JavaScript: either using dot notation, or using square bracket notation (required for field names that contain spaces or special characters).

For example, to insert the value of a column named phone_number in the input data, write the expression {{$json.phone_number}} (dot notation) or {{$json["phone_number"]}} (square bracket notation).

Expressions must be single-line, i.e., the {{ and }} must be on the same line. Adding a line break in the middle of an expression will cause it to be interpreted as literal text instead.

Example of the dialog box for editing an expression. Dynamic values (within double curly brackets) are highlighted in green, text outside is unchanged. A preview of the expression result is shown below. A list of input data to the connector is visible on the left side-bar of the dialog box (Input data is only visible if the previous connector has been executed first.)

In addition to its immediate input, expressions can also access the output data of other connectors in the workflow. These can be accessed using the $node keyword, followed by the unique connector ID.

The connector ID is not usually displayed in the workflow, so the easiest to use data from other connectors is by selecting it the left side-bar in the 'Edit Expression' dialog box, rather than typing the connector ID.

In order to access the output data of another connector, that connector must run before the connector containing the expression does. The expression will be evaluated with empty data otherwise.

Referring to data using $node rather than $json can make your workflow more brittle, as you are more likely to encounter errors if the referenced connector is moved or deleted, or the connectors in the workflow are re-connected in a different order. Because of this, it is recommended to prefer using $json over $node where possible.

JavaScript in expressions

In addition to referring to JSON fields, it is possible to include JavaScript expressions (but not JavaScript statements) within an expression. For example, to display the string in the myString field from the input JSON in all-caps, you can use the expression: {{$json.myString.toUpperCase()}}. This allows you to make simple changes to the input data without requiring a "Function" connector.

NOTE: Variables in expressions produce output that is meant to be used as part of plain text, and differ slightly from the results of calling .toString() in JavaScript. In particular, the results of expressions are usually not suitable for being returned as a JSON string (for example, in "Respond to Webhook" connectors). In order to ensure that the result is a valid JSON string, you should include a call to the JSON.stringify() function in the expression, for example: {{JSON.stringify($json.someData)}}.

You can also perform checks and set default values within expressions using the optional chaining (?.), ternary (?:), null coalescing (??), and logical OR (||) operators from JavaScript. This allows you to perform simple handling of data that is potentially missing or invalid without requiring a "Function" connector.

Examples:

// Check if the input JSON contains a `myString` value.
// If `myString` does not exist,
// the expression will evaluate to 'default value'.
// Otherwise it will evaluate to the text within `myString`,
// possibly an empty string.
{{ $json.myString ?? 'default value' }}

// Similar to above, but now if `myString` is an empty string,
// the expression will evaluate to 'default value' instead.
{{ $json.myString || 'default value' }}

// Check if the input JSON contains a `myString` field
// before trying to use the `.toLowerCase()` method.
// If `myString` does not exist or is an empty string,
// the expression will evaluate to 'default value'.
{{ $json.myString ? $json.myString.toLowerCase() : 'default value' }}

// Same as above, but using optional chaining
// instead of the ternary operator.
{{ $json.myString?.toLowerCase() || 'default value' }}

Other input data

In addition to JSON input, binary input (e.g., downloaded files) can also be accessed and manipulated in expressions using the $binary prefix. However, this is much less-frequently used compared to $json, since most connectors that work with binary input do not usually use expressions using $binary, but rather use the name of a field within the binary input in order to determine which data to access.

Related syntax in "Function" connectors

"Function" connectors allow you to modify data using JavaScript. The syntax for accessing input data is similar to that used in expressions. "Function" connectors accept input (which may have more than one row) as an array of objects that each have a json field. The fields within the json field can be accessed similarly as in expressions. Example:

// Loop over the rows (items) of the input data.
for (item of items) {
  // Access `myNumber` from JSON of each input item.
  // Compare expression syntax: {{$json.myNumber}}
  const myNumber = item.json.myNumber;

  if (myNumber > 5) {
    // Access JSON of each item and add a new field called `myString`.
    item.json.myString = "Example string.";
  }
}

// NOTE: "Function" connectors must explicitly return their output.
return items;