Variable insertion

Variable insertion (Interpolation) is a way to dynamically modify a string expression or object at runtime.

Usage Engine uses curly brackets to indicate that a variable insertion will take place. Variable insertion is supported in some functions' configuration settings, like https://infozone.atlassian.net/wiki/spaces/DAZ/pages/7897286 and https://infozone.atlassian.net/wiki/spaces/DAZ/pages/7798876.

Within the curly brackets, you can access variables that belong to different scopes and use them to generate a dynamically changed output at runtime. Depending on what you want to achieve or manipulate, the output from variable insertion can be a string (if prefixed by '$') or an object( if prefixed by '@' ).

Scopes

Usage Engine allows you to perform Variable Insertion using the following scopes:

payload
meta
sharedStore

The table below provides an overview of how to use these scopes, accompanied by a few examples. You can also perform nested Variable Insertion using the same or different scopes.

Note!

While using '$' or '@', note the following:

${scope} will result in a string. ${scope} behaves like a JavaScript template Variable Insertion with the following exceptions:
- Returns 'undefined' instead of throwing an error when accessing non-existent paths
- Returns full object (payload) for ${payload}
- Returns a JSON representation of objects instead of [Object object]

@{scope} will result in an object

Caution!

You must not use special characters, such as the dollar sign ($), ampersand (&), at sign (@), or curly braces ({ }), in field names when you use interpolation, because these characters are reserved for interpolation and cause errors or unexpected behavior if included.

For example, ${payload.myValue} works as expected, but ${payload.my$value} does not.

Example - Nested data structure
If you have a nested data structure in payload.foo and want to preserve the structure without transforming it into a string, then you must use @{payload}.foo} instead of ${payload.foo}.

Variable insertion with scopes

You can use variable insertion using the following scopes/variables/objects only:

Scope	Explanation	Example

Scope

Explanation

Example

payload

You can perform variable insertion on any data from the current record.
The payload scopes cover any content that is sent from one node to the next.

Payload type variable insertion can be used to address the data flowing through the stream.

Note!
The Payload scope is not accessible for collector functions.

// Payload = { 
  
allFruits: 
{ 
    banana: 1, 
    apple: 2, 
    orange: 3 
 }, 
  myFruit: 'apple' 
}

To access apple you can use Variable Insertion like: ${payload.myFruit}

or,

if you want to use nested Variable Insertion, you can use square brackets '[]'

${payload.allFruits[apple]} ---> The result will be 2

meta

Meta covers additional information that gives further context to the data (metadata).

meta type variable insertion is designated to process the accompanying metadata.

You can use variable insertion using any data from the current record's metadata. You can use meta with a processor or a forwarder function.

Note!
The meta scope is not accessible for collector functions.

For example, if you want to try to read from an Amazon S3 forwarder function using a Script function:

meta.fileName = "myFile"
    log.info(meta.fileName);
await push(payload);

And, do variable insertion on the filename:
${meta.fileName}${payload.value}

Once you run the stream, you will find the files in S3 forwarder with the following format:
myFile<count of the file>_<timestamp>.csv

sharedStore

Data that is currently stored in the shared store.

The sharedStore property allows you to define your variable and use it across different streams.

The sharedStore scope is loaded during the start of the stream and the content does not change during the execution. So, if you have done any changes to the sharedStore variable that will take effect in the subsequent execution only.

See https://infozone.atlassian.net/wiki/spaces/DAZ/pages/7897286 for more information.

sharedStore:
      1 = 5.csv
      2 = 10.csv
      anotherProperty = { 
        first: 
{ 
          second: "third" 
        } 
      }

${sharedStore[1]} ----> 5.csv

// SharedStore = { file1: 'my-first-file.csv', file2: 'my-second-file.csv'}