0
# Data Proxy System
1

2
Advanced data proxy system for accessing workflow data, resolving parameters, and handling complex data transformations with full context awareness and parameter resolution.
3

4
## Capabilities
5

6
### WorkflowDataProxy Class
7

8
Core data proxy providing context-aware access to workflow execution data.
9

10
```typescript { .api }
11
/**
12
 * Workflow data proxy for context-aware data access
13
 */
14
class WorkflowDataProxy {
15
  /**
16
   * Create data proxy for workflow execution context
17
   * @param workflow - Current workflow instance
18
   * @param runExecutionData - Current execution data
19
   * @param runIndex - Current run index
20
   * @param itemIndex - Current item index
21
   * @param node - Current node
22
   * @param connectionInputData - Input data from connections
23
   * @param siblingParameters - Sibling node parameters
24
   * @param mode - Execution mode
25
   * @returns Data proxy object with context access
26
   */
27
  static getDataProxy(
28
    workflow: Workflow,
29
    runExecutionData: IRunExecutionData,
30
    runIndex: number,
31
    itemIndex: number,
32
    node: INode,
33
    connectionInputData: INodeExecutionData[],
34
    siblingParameters?: INodeParameters,
35
    mode?: WorkflowExecuteMode
36
  ): IDataObject;
37
}
38
```
39

40
### Data Access Context Objects
41

42
Context objects providing access to different types of workflow data.
43

44
```typescript { .api }
45
/**
46
 * JSON data access context
47
 */
48
interface IJsonDataContext {
49
  [key: string]: any;
50
}
51

52
/**
53
 * Binary data access context
54
 */
55
interface IBinaryDataContext {
56
  [key: string]: IBinaryData;
57
}
58

59
/**
60
 * Node parameter access context
61
 */
62
interface IParameterDataContext {
63
  [key: string]: NodeParameterValue | INodeParameters;
64
}
65

66
/**
67
 * Execution environment context
68
 */
69
interface IEnvironmentDataContext {
70
  [key: string]: string | undefined;
71
}
72

73
/**
74
 * Input data access context
75
 */
76
interface IInputDataContext {
77
  all: INodeExecutionData[];
78
  first: INodeExecutionData;
79
  last: INodeExecutionData;
80
  item: INodeExecutionData;
81
}
82
```
83

84
### Environment Data Provider
85

86
Environment variable provider for secure access to system environment variables.
87

88
```typescript { .api }
89
/**
90
 * Environment data provider for workflow execution
91
 */
92
interface IWorkflowDataProxyEnvProvider {
93
  /**
94
   * Get environment variable value
95
   * @param name - Environment variable name
96
   * @returns Environment variable value or undefined
97
   */
98
  getEnv(name: string): string | undefined;
99

100
  /**
101
   * Check if environment variable exists
102
   * @param name - Environment variable name
103
   * @returns Boolean indicating if variable exists
104
   */
105
  hasEnv(name: string): boolean;
106
}
107

108
interface EnvProviderState {
109
  isEnvAccessBlocked: boolean;
110
  allowedEnvVars: Set<string>;
111
}
112

113
/**
114
 * Create environment provider with access controls
115
 * @param state - Environment provider state
116
 * @returns Environment provider instance
117
 */
118
function createEnvProvider(state: EnvProviderState): IWorkflowDataProxyEnvProvider;
119
```
120

121
### Data Resolution Functions
122

123
Functions for resolving different types of data in workflow context.
124

125
```typescript { .api }
126
/**
127
 * Resolve node parameters with expression evaluation
128
 * @param workflow - Current workflow
129
 * @param runExecutionData - Execution data
130
 * @param runIndex - Run index
131
 * @param node - Current node
132
 * @param nodeParameters - Parameters to resolve
133
 * @param connectionInputData - Input data
134
 * @param mode - Execution mode
135
 * @returns Resolved parameters
136
 */
137
function resolveNodeParameters(
138
  workflow: Workflow,
139
  runExecutionData: IRunExecutionData,
140
  runIndex: number,
141
  node: INode,
142
  nodeParameters: INodeParameters,
143
  connectionInputData: INodeExecutionData[],
144
  mode: WorkflowExecuteMode
145
): INodeParameters;
146

147
/**
148
 * Get execution data for specific node
149
 * @param workflow - Current workflow
150
 * @param runExecutionData - Execution data
151
 * @param runIndex - Run index
152
 * @param nodeName - Node name to get data for
153
 * @returns Node execution data
154
 */
155
function getNodeExecutionData(
156
  workflow: Workflow,
157
  runExecutionData: IRunExecutionData,
158
  runIndex: number,
159
  nodeName: string
160
): ITaskData[] | undefined;
161

162
/**
163
 * Get workflow static data with context
164
 * @param workflow - Current workflow
165
 * @param type - Static data type
166
 * @returns Static data object
167
 */
168
function getWorkflowStaticData(
169
  workflow: Workflow,
170
  type: string
171
): IDataObject;
172
```
173

174
### Data Proxy Helpers
175

176
Helper functions for common data proxy operations and transformations.
177

178
```typescript { .api }
179
/**
180
 * Create item data context for expressions
181
 * @param item - Current item data
182
 * @param itemIndex - Item index
183
 * @returns Item context object
184
 */
185
function createItemContext(
186
  item: INodeExecutionData,
187
  itemIndex: number
188
): IDataObject;
189

190
/**
191
 * Create input data context
192
 * @param inputData - Input data array
193
 * @param itemIndex - Current item index
194
 * @returns Input data context
195
 */
196
function createInputDataContext(
197
  inputData: INodeExecutionData[],
198
  itemIndex: number
199
): IInputDataContext;
200

201
/**
202
 * Create previous node data context
203
 * @param workflow - Current workflow
204
 * @param runExecutionData - Execution data
205
 * @param node - Current node
206
 * @param itemIndex - Item index
207
 * @returns Previous node data context
208
 */
209
function createPreviousNodeContext(
210
  workflow: Workflow,
211
  runExecutionData: IRunExecutionData,
212
  node: INode,
213
  itemIndex: number
214
): IDataObject;
215

216
/**
217
 * Augment data object with proxy methods
218
 * @param data - Data object to augment
219
 * @param context - Augmentation context
220
 * @returns Augmented data object
221
 */
222
function augmentObject<T extends object>(
223
  data: T,
224
  context: IAugmentObjectContext
225
): T;
226

227
interface IAugmentObjectContext {
228
  allowedKeys?: string[];
229
  blockedKeys?: string[];
230
  includeHidden?: boolean;
231
}
232
```
233

234
### Parameter Resolution
235

236
Advanced parameter resolution with type coercion and validation.
237

238
```typescript { .api }
239
/**
240
 * Resolve parameter value with type conversion
241
 * @param parameterValue - Parameter value to resolve
242
 * @param type - Expected parameter type
243
 * @param context - Resolution context
244
 * @returns Resolved and typed parameter value
245
 */
246
function resolveParameterValue(
247
  parameterValue: NodeParameterValue,
248
  type: NodeParameterType,
249
  context: IParameterResolutionContext
250
): any;
251

252
interface IParameterResolutionContext {
253
  workflow: Workflow;
254
  runExecutionData: IRunExecutionData;
255
  runIndex: number;
256
  itemIndex: number;
257
  node: INode;
258
  connectionInputData: INodeExecutionData[];
259
  mode: WorkflowExecuteMode;
260
}
261

262
/**
263
 * Convert parameter to specified type
264
 * @param value - Value to convert
265
 * @param toType - Target type
266
 * @returns Converted value
267
 */
268
function convertParameterType(
269
  value: any,
270
  toType: NodeParameterType
271
): any;
272

273
type NodeParameterType = 
274
  | 'string'
275
  | 'number' 
276
  | 'boolean'
277
  | 'object'
278
  | 'array'
279
  | 'dateTime'
280
  | 'json'
281
  | 'notice'
282
  | 'collection'
283
  | 'fixedCollection'
284
  | 'multiOptions'
285
  | 'options'
286
  | 'color'
287
  | 'hidden'
288
  | 'resourceLocator'
289
  | 'resourceMapper'
290
  | 'filter'
291
  | 'assignmentCollection';
292
```
293

294
**Usage Examples:**
295

296
```typescript
297
import { 
298
  WorkflowDataProxy, 
299
  resolveNodeParameters, 
300
  createInputDataContext 
301
} from "n8n-workflow";
302

303
// Create data proxy for expression resolution
304
const dataProxy = WorkflowDataProxy.getDataProxy(
305
  workflow,
306
  runExecutionData,
307
  0, // runIndex
308
  0, // itemIndex  
309
  currentNode,
310
  connectionInputData
311
);
312

313
// Access different data contexts
314
console.log('Current item JSON:', dataProxy.$json);
315
console.log('Input data:', dataProxy.$input);
316
console.log('Node parameters:', dataProxy.$parameter);
317
console.log('Environment variables:', dataProxy.$env);
318

319
// Resolve node parameters with expressions
320
const resolvedParameters = resolveNodeParameters(
321
  workflow,
322
  runExecutionData,
323
  0, // runIndex
324
  currentNode,
325
  {
326
    apiUrl: "{{ $env.API_BASE_URL }}/users/{{ $json.userId }}",
327
    timeout: "{{ $parameter.requestTimeout || 30000 }}",
328
    headers: {
329
      'Authorization': "Bearer {{ $credentials.accessToken }}",
330
      'Content-Type': 'application/json'
331
    }
332
  },
333
  connectionInputData,
334
  'manual'
335
);
336

337
// Create input data context for expressions
338
const inputContext = createInputDataContext(connectionInputData, 0);
339
console.log('First input item:', inputContext.first);
340
console.log('All input items:', inputContext.all);
341
console.log('Current input item:', inputContext.item);
342

343
// Access previous node data
344
const previousNodeData = dataProxy.$node["HTTP Request"];
345
console.log('Previous node output:', previousNodeData.json);
346
console.log('Previous node binary:', previousNodeData.binary);
347

348
// Environment variable access (with security controls)
349
const envProvider = createEnvProvider({
350
  isEnvAccessBlocked: false,
351
  allowedEnvVars: new Set(['API_BASE_URL', 'DATABASE_URL'])
352
});
353

354
const apiUrl = envProvider.getEnv('API_BASE_URL');
355
if (apiUrl) {
356
  console.log('API URL from environment:', apiUrl);
357
}
358

359
// Complex expression resolution
360
const expressionResult = dataProxy.$evaluateExpression(`
361
  {{
362
    $input.all
363
      .filter(item => item.json.status === 'active')
364
      .map(item => ({
365
        id: item.json.id,
366
        name: item.json.name,
367
        createdAt: item.json.createdAt.format('yyyy-MM-dd')
368
      }))
369
  }}
370
`);
371
```