Variable insertion scope details

This section describes the scopes that you can use with variable insertion in Usage Engine. It explains the payload, meta, and sharedStore scopes and shows how to reference their properties in expressions.

`payload`

The payload scope addresses data flowing through the stream from one function to the next.

Example - Using variable insertion with payload data

// Payload = {
//   allFruits: { banana: 1, apple: 2, orange: 3 },
//   myFruit: "apple"
// }
${payload.myFruit}              // Returns: "apple"
${payload.allFruits.banana}     // Returns: "1"
${payload.allFruits}            // Returns: '{"banana":1,"apple":2,"orange":3}'

Note!
The payload scope is not available in collector-type functions.

`meta`

The meta scope provides access to metadata that gives additional context about the data being processed. Common meta properties include:

Property	Description

Property	Description
fileName	Name of the source file
filePath	Full path to the source file
fileSize	Size of the source file
sheetName	Name of the sheet (for spreadsheet sources)
collectionTime	Timestamp when data was collected
streamId	Identifier for the current stream

Example - Read from an Amazon S3 forwarder with Script

Example stream

// In a Script function before the S3 forwarder:
meta.fileName = "myFile";
log.info(meta.fileName);
await push(payload);
// Variable insertion on the filename:
${meta.fileName}${payload.value}
// Result: Files in S3 with format: myFile<count>_<timestamp>.csv

Amazon S3 configuration

For a detailed example, see https://infozone.atlassian.net/wiki/spaces/DAZ/pages/849281083.

Note!
The meta scope is not available in collector-type functions.

`sharedStore`

The sharedStore scope allows you to define variables and use them across different streams. The sharedStore content is loaded when the stream starts and does not change during execution. Any changes made to sharedStore variables take effect only in subsequent executions.

Example - Using sharedStore values across streams

In this example, the shared store contains two CSV filenames and a nested object. You can reference the filenames by key in your expressions.

sharedStore:
  1 = 5.csv
  2 = 10.csv
  anotherProperty = { 
    first: { 
      second: "third"
    } 
  }
${sharedStore[1]} ----> 5.csv
// Alternative structure:
// sharedStore = { file1: 'my-first-file.csv', file2: 'my-second-file.csv' }

Advanced usage

Square bracket notation

Use square brackets to access properties dynamically:

// Payload = { fruits: { banana: 1, apple: 2 } }
${payload[fruits]}           // Returns: '{"banana":1,"apple":2}'
${payload[fruits][banana]}   // Returns: "1"

Nested variable insertion

You can nest variable insertions to create dynamic property paths. Nesting is supported up to 20 levels deep.

Example - Nested variable insertion

// Payload = {
//   allFruits: { banana: 1, apple: 2, orange: 3 },
//   myFruit: "apple"
// }
${payload.allFruits[${payload.myFruit}]}  // Returns: "2"

Example - Advanced nesting

The following example shows nested variable insertion across meta, payload, and sharedStore to build a dynamic path.

// meta = { topic: "fruits", origin: "banana" }
// payload = { fruits: { banana: 1 } }
// sharedStore = { 1: { data: "found" } }
${sharedStore[@{payload[${meta.topic}][${meta.origin}]}]}
// Step 1: ${meta.topic} → "fruits"
// Step 2: ${meta.origin} → "banana"
// Step 3: @{payload[fruits][banana]} → 1
// Step 4: ${sharedStore[1]} → '{"data":"found"}'

For character restrictions in field names, see https://infozone.atlassian.net/wiki/spaces/DAZ/pages/1066074242/Variable+insertion+syntax+and+behavior#Character-restrictions.

Error handling

Variable insertion throws an error in the following cases:

Condition	Error message

Condition	Error message
Invalid or unsupported scope	"Interpolation scope is not defined or is not supported for [expression]."
Malformed syntax (for example, unclosed brackets)	Syntax error
Exceeded nesting depth (more than 20 levels)	"Max level of interpolation exceeded (20)."