Variable insertion syntax and behavior

This section describes the syntax and behavior of variable insertion in Usage Engine. It explains how ${} and @{} work, how they handle nested data structures, and which characters are allowed in field names in expression‑based nodes and other parameters.

String output with `${}`

${scope.path} returns a string value with the following behaviors:

Returns 'undefined' as a string when accessing non-existent paths (does not throw an error)
Returns the full object as a JSON string for ${payload}
Converts objects to their JSON representation instead of [Object object]
Converts Date objects to ISO 8601 format strings

Examples ${}:

// Payload = { name: "Alice", count: 42 }
${payload.name}     // Returns: "Alice"
${payload.count}    // Returns: "42"
${payload}          // Returns: '{"name":"Alice","count":42}'
${payload.missing}  // Returns: "undefined"

Object output with `@{}`

@{scope.path} returns the actual object value:

Returns undefined (the value, not a string) when accessing non-existent paths
Preserves nested data structures without converting them to strings

Examples @{}:

// Payload = { user: { name: "Alice", roles: ["admin", "user"] } }
@{payload.user}        // Returns: { name: "Alice", roles: ["admin", "user"] }
@{payload.user.roles}  // Returns: ["admin", "user"]
@{payload.missing}     // Returns: undefined (field is omitted)

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

Character restrictions

When you use variable insertion, certain special characters are reserved by the system and cannot appear in field names. The specific restrictions depend on where you are using the variable insertion.

In expression-based nodes

When you use variable insertion in nodes that evaluate expressions (such as Map or Route ), field names must contain only:

Letters (a-z, A-Z)
Numbers (0-9)
Underscores (_)
Dots (.)

Special characters such as the dollar sign ($), ampersand (&), at sign (@), curly braces ({ }), hash (#), and percent (%) for accessing nested properties, are not allowed and cause errors or unexpected behavior.

Example - Use of special characters

// Payload = { myValue: "Alice", my_value: "Bob" }                                                                                                                                          
  ${payload.myValue}      // Returns: "Alice"                                                                                                                                                 
  ${payload.my_value}     // Returns: "Bob"                                                                                                                                                   
  ${payload.my&value}     // Does not work - & is not allowed                                                                                                                                 
  ${payload.my$value}     // Does not work - $ is not allowed

In other parameters

When you use variable insertion in non-expression parameters (such as file paths, URLs, or HTTP headers), the restrictions are less strict. Only these four characters are reserved:

Dollar sign ($)
At sign (@)
Opening curly brace ({)
Closing curly brace (})

Other special characters, including the ampersand (&), are allowed in these contexts.

Example - Special characters in non-expression parameters

// Payload = { "my&value": "data", "my@value": "test" }                                                                                                                                     
  ${payload.my&value}     // Returns: "data" - works in file paths and HTTP headers                                                                                                           
  ${payload.my@value}     // Does not work - @ is always reserved

Note!
For consistent behavior across all function types, avoid using special characters in field names entirely.

For details about available scopes, see Variable insertion scope details. For worked examples, see Variable insertion examples.