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. The variable insertion is supported in some Functions' configuration fields and also within Script and Script Aggregator Functions.
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 '@' ).
Example
Consider a scenario where you want to send the same message to different customers and insert the customer name in the message at runtime.
payload.customer_name = "Johnny";
payload.full_message = `Hello ${payload.customer_name}. You have received a new mail.`;
await push(payload);
And this is what the Variable Insertion in the Email Notification Function looks like:
When you run this code, the intended recipient (Johnny in this case) will see an email with the following content:
Hello Johnny. You have received a new mail.
Scopes
Usage Engine allows you to perform Variable Insertion using the following scopes only.
- payload
- meta
- deploy
- sharedStore
Refer to the Variable Insertion#table below to know how to use these scopes with a few examples. You can also perform nested Variable Insertion using the same or different scopes.
$ or @
While using '$' or '@', note the following:
${scope} will result in a string. ${scope} behaves like a JavaScript template Variable Insertion with the following exceptions:
@{scope} will result in an object
Example
If you have a nested data structure in payload.foo, and you want to keep the structure and not transform 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 |
|---|---|---|
You can perform Variable Insertion on any data from the current record.
Note! The | // Payload = {
allFruits:
{
banana: 1,
apple: 2,
orange: 3
},
myFruit: 'apple'
}
To access 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).
You can use Variable Insertion using any data from the current record's metadata. You can use Note! The | 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: Once you run the stream, you will find the files in S3 Forwarder with the following format: |
deploy | You can use Variable Insertion using replicaNumber and lastReplicaNumber properties only.When running a stream with multiple replicas, the first instance would be identified as the first replica. This is represented in the The For more information about replicas, see Performance and scalability. | For example, To access the second instance of a replica with a total of three instances running:
You can use Variable Insertion like: ${deploy.replicaNumber} ----> 2
//or, nested Variable Insertion:
${deploy.[${deploy.lastReplicaNumber}+${deploy.replicaNumber}]}
|
sharedStore | Data that is currently stored in the shared store. The The Refer Script for more information. | sharedStore:
1 = 5.csv
2 = 10.csv
anotherProperty = {
first:
{
second: "third"
}
}
${sharedStore[1]} ----> 5.csv
${sharedStore[${sharedStore.replicaNumber}]} ----> 5.csv
// SharedStore = { file1: 'my-first-file.csv', file2: 'my-second-file.csv'}
${sharedStore[file${deploy.replicaNumber}]}
---> 'my-first-file.csv' for replica 1
---> 'my-second-file.csv' for replica 2
|
Examples
See Variable Insertion using HTTP Client for a few examples of variable substitution using HTTP Client.