This page covers how n8n makes workflow state available to nodes and expressions at runtime: the WorkflowDataProxy class that builds the $-variable namespace, the expression parsing and evaluation pipeline, the NodeHelpers parameter-resolution utilities, and the Workflow class methods that traverse the node graph. For the lifecycle of a workflow execution itself, see Workflow Execution Lifecycle. For how partial re-runs and dirty-node analysis work, see Partial Execution and Error Handling. For how the expression editor is presented in the UI, see Parameter Input and Expression Editor.
Node parameters may contain three kinds of value:
| Form | Example | Meaning |
|---|---|---|
| Plain literal | hello | Stored and used as-is |
| Full-expression | ={{ $json.name }} | Entire field is evaluated as JS |
| Mixed string | Hello, {{ $json.name }}! | Template literal, parts are evaluated |
The leading = signals that the value is expression-enabled. The double-brace {{ ... }} region is the JS fragment that is evaluated. A field value starting with = but containing no {{ }} is treated as a plain expression string that is evaluated in its entirety.
The constant FROM_AI_AUTO_GENERATED_MARKER (/*n8n-auto-generated-fromAI-override*/) is a special comment injected before AI-generated $fromAI(...) expressions so tooling can distinguish them from user-written ones:
={{ /*n8n-auto-generated-fromAI-override*/ $fromAI('Start', ``, 'string') }}
Sources: packages/workflow/src/constants.ts128 packages/workflow/test/fixtures/WorkflowDataProxy/agentInfo_workflow.json44-46
Expression class (packages/workflow/src/expression.ts) is the entry point for all expression evaluation. It:
=).{{ ... }} delimiters.Function construction.WorkflowDataProxy as the this/scope context.NodeParameterValueType.Higher-level functions on node execution contexts delegate to this class:
evaluateExpression(expression: string, itemIndex: number): NodeParameterValueType
This method signature is part of BaseExecutionFunctions and is available on every node execution context (IExecuteFunctions, ISupplyDataFunctions, etc.).
Evaluation flow diagram:
Sources: packages/workflow/src/interfaces.ts1019
WorkflowDataProxy (in packages/workflow/src/workflow-data-proxy.ts) is a JavaScript Proxy-based object that wraps all workflow state for a specific item index. It is constructed once per item per node execution and passed to the expression evaluator as the variable scope.
| Input | Type | Purpose |
|---|---|---|
workflow | Workflow | Graph traversal, metadata |
runExecutionData | IRunExecutionData | All run data for all nodes |
runIndex | number | Which run of the current node |
connectionInputData | INodeExecutionData[] | Input items to the current node |
activeNodeName | string | The node being executed |
itemIndex | number | Which input item to scope to |
executeData | IExecuteData | Source node metadata |
additionalData | IWorkflowExecuteAdditionalData | Credentials helper, instance URL, etc. |
mode | WorkflowExecuteMode | Execution mode |
$-variable namespaceThe proxy object exposes the following top-level bindings:
| Variable | Description |
|---|---|
$json | JSON fields of the current input item (connectionInputData[itemIndex].json) |
$binary | Binary fields of the current input item |
$input | Full input object with .item, .all(), .first(), .last() helpers |
$node["Name"] | Access output data, parameters, or context of any named node |
$('Node Name') | Shorthand functional form of $node |
$workflow | Workflow metadata (id, name, active) |
$execution | Execution metadata (id, mode, resumeUrl) |
$runIndex | Zero-based index of the current run |
$itemIndex | Zero-based index of the current item |
$prevNode | Name and output index of the previous node in the path |
$vars | Workflow-level variables from n8n Variables |
$env | Environment variables (filtered by EnvProviderState) |
$secrets | External secrets (e.g. from vault providers) |
$now | Current DateTime (Luxon object) |
$today | Start of today as a DateTime |
$jmespath | JMESPath query function |
$fromAI(key, desc, type) | Placeholder resolved by AI agent tool calls |
$node accessor structure$node["NodeName"] returns a sub-proxy with:
.json ā JSON of the node's output item at the current item index.binary ā binary output.context ā node-level context data.runIndex ā which run of that node.params ā parameters of that node (resolved).outputIndex ā which output branch to useWorkflowDataProxyEnvProvider (imported as EnvProviderState in interfaces.ts) controls which environment variables are visible inside expressions. It is supplied to WorkflowDataProxy at construction and can restrict access based on instance configuration.
Sources: packages/workflow/src/interfaces.ts41 packages/workflow/src/interfaces.ts1022
IWorkflowDataProxyData is the TypeScript interface that documents the shape of the proxy object. The getWorkflowDataProxy(itemIndex: number): IWorkflowDataProxyData method on BaseExecutionFunctions and ISupplyDataFunctions returns an instance of this type.
Node code can call this method to obtain the same data proxy that the expression evaluator uses:
getWorkflowDataProxy(itemIndex: number): IWorkflowDataProxyData
This is useful for nodes that need to programmatically inspect the proxy without going through expression evaluation.
Sources: packages/workflow/src/interfaces.ts1022 packages/workflow/src/interfaces.ts1144
packages/workflow/src/node-helpers.ts provides getNodeParameters, the central utility for resolving a set of raw node parameters against their type descriptions.
getNodeParameters signatureIt:
INodeProperties[] type description.displayOptions logic to skip hidden parameters.default values when a parameter is absent and returnDefaults is true.INodeParameters object.This function does not evaluate expressions ā it works with raw stored values. Expression evaluation happens separately in Expression when a node actually runs.
IGetNodeParameterOptionsHigher-level helpers like getNodeParameter(name, itemIndex, fallback, options) on all execute-function interfaces accept IGetNodeParameterOptions:
| Option | Type | Effect |
|---|---|---|
ensureType | EnsureTypeOptions | Coerce value to string, number, boolean, object, array, or json |
extractValue | boolean | For resourceLocator parameters, extract the .value field |
rawExpressions | boolean | Return the raw expression string without evaluating it |
skipValidation | boolean | Skip parameter validation |
contextNode | INode | Use a different node as expression context |
Sources: packages/workflow/src/interfaces.ts619-630 packages/workflow/src/interfaces.ts664-701 packages/workflow/src/telemetry-helpers.ts50-51 packages/workflow/src/telemetry-helpers.ts292-306
Workflow (in packages/workflow/src/workflow.ts) is the primary in-memory representation of the workflow graph. It owns the nodes map and the connections structure and provides traversal helpers used by both the execution engine and the data proxy.
| Method | Description |
|---|---|
getNode(nodeName) | Look up a node by name |
getChildNodes(nodeName, type?, depth?) | All downstream (consumer) nodes |
getParentNodes(nodeName, type?, depth?) | All upstream (producer) nodes |
getConnectedNodes(connections, nodeName, type, depth) | General directional traversal |
getNodeConnectionIndexes(nodeName, parentNodeName, type) | Which input/output indexes connect two nodes |
getSimplifiedNodeType(node) | Get resolved ISimplifiedNodeType for a node |
getStaticData(type, node) | Read/write node or workflow static data |
getHighestNode(names, nodeData, runIndex, itemIndex, siblingParameters) | Find topmost reachable node in a set |
These are called inside WorkflowDataProxy to resolve $node["Name"] and $prevNode, and inside FunctionsBase to implement getChildNodes() and getParentNodes() on execution contexts.
The type field on IConnection uses NodeConnectionType constants (e.g., NodeConnectionTypes.Main, NodeConnectionTypes.AiTool, NodeConnectionTypes.AiLanguageModel). This is how AI sub-nodes (tools, LLMs, memory) are distinguished from regular data flow connections.
Sources: packages/workflow/src/interfaces.ts89-98 packages/workflow/src/interfaces.ts404-418 packages/workflow/src/telemetry-helpers.ts847-858
Workflow static data persists between executions. It is accessed from nodes via getWorkflowStaticData(type: string) on FunctionsBase:
type = 'global' ā shared across all nodes in the workflowtype = 'node' ā scoped to the calling nodeThe data is stored in IRunExecutionData.resultData.staticData and written back to the database after each execution.
Sources: packages/workflow/src/interfaces.ts958
In addition to run data, each execution has a context store accessed via getContext(type: ContextType) on BaseExecutionFunctions:
| Context type | Key pattern | Use |
|---|---|---|
'flow' | "flow" | Shared across all nodes in the execution |
'node' | "node:<NODE_NAME>" | Private to a specific node |
Context is stored in IRunExecutionData.executionData.contextData as IExecuteContextData and does not persist between separate executions.
Sources: packages/workflow/src/interfaces.ts457-464 packages/workflow/src/interfaces.ts994 packages/workflow/src/interfaces.ts1020
The following diagram maps the full call chain from a raw parameter string in node configuration to a resolved runtime value, naming the code entities involved at each step:
Sources: packages/workflow/src/interfaces.ts664-701 packages/workflow/src/interfaces.ts1016-1022 packages/workflow/src/telemetry-helpers.ts50-51
Credentials can also contain expressions. The ICredentialsExpressionResolveValues interface bundles the context needed to evaluate them:
ICredentialsHelper.getDecrypted(...) accepts an optional expressionResolveValues parameter to trigger expression resolution on credential fields before returning them to a node.
Sources: packages/workflow/src/interfaces.ts172-179 packages/workflow/src/interfaces.ts233-241
| Entity | File | Role |
|---|---|---|
WorkflowDataProxy | packages/workflow/src/workflow-data-proxy.ts | Builds the $-variable proxy for expression evaluation |
Expression | packages/workflow/src/expression.ts | Parses and evaluates ={{ ... }} strings |
getNodeParameters | packages/workflow/src/node-helpers.ts | Resolves raw parameter values against type descriptions |
Workflow | packages/workflow/src/workflow.ts | Graph model; getChildNodes, getParentNodes, getStaticData |
WorkflowDataProxyEnvProvider | packages/workflow/src/workflow-data-proxy-env-provider.ts | Filters env var visibility in expressions |
IWorkflowDataProxyData | packages/workflow/src/interfaces.ts | TypeScript shape of the $-proxy object |
IGetNodeParameterOptions | packages/workflow/src/interfaces.ts | Options for parameter retrieval (ensureType, extractValue, etc.) |
ICredentialsExpressionResolveValues | packages/workflow/src/interfaces.ts | Context bundle for credential expression evaluation |
Sources: packages/workflow/src/interfaces.ts41 packages/workflow/src/interfaces.ts172-179 packages/workflow/src/interfaces.ts619-630 packages/workflow/src/interfaces.ts1016-1026
Refresh this wiki
This wiki was recently refreshed. Please wait 2 days to refresh again.