Interpolation Syntax Reference
1. What you will learn
In PAK there is the possibility to interpolate values when mapping values from Command to Command.
This short Guide will show you how what is possible.
2. Basic Interpolation
All interpolations start off with a dollar sign and an open curly bracket that encloses the mapping together with a finalizing closed curly bracket.
An escaped interpolation like \${something} will not be recognized by the engine and kept as is.
|
Interpolation ⇒ ${InterpolationValue}
InterpolationValue ⇒ Environment | JsonPath
Interpolations may either enclose an environment variable or the json path to a variable stored in the datastore.
3. Environmental Interpolation
Environment ⇒ java(text) | env(text)
text: Name of the variable to fetch.
Environmental Interpolation refers to the acquisition of variables from the engines environment.
To fetch a java runtime property use java, to fetch a systems environment variable use env.
4. Json Path Interpolation
JsonPath ⇒ JsonVariable(.JsonVariable)*
JsonVariable ⇒ ArrayIdentifier | text ArrayIdentifier?
ArrayIdentifier ⇒ [number] | [:] | [-:]
text: Name of the variable in the preceding element
number: Positive integer within the bounds of the preceding json array
Using json path interpolation, values from the datastore can be fetched and mapped directly from the datastore.
The name of the first element in the json path must refer to a key that is present in the datastore.
When the preceding element is a json array, but no identifier was given, the whole json array is mapped to the declared variable and returned.
Special array identifiers:
-
[:] refers to the first element in the preceding array
-
[-:] refers to the last element in the preceding array
4.1. Examples
Given the following json object which is stored in the datastore under the key ‚obj‘:
{
"name" : "Max",
"age" : 33,
"hobbies" : [
{
"name" : "Soccer",
"id" : 0
},
{
"name" : "Coding",
"id" : 1
},
{
"name" : "Automating Workflows",
"id" : 2
}
]
}-
obj.name → „Max“
-
obj.age → 33
-
obj.hobbies[1] → {„name“ : „Coding“, „id“ : 1}
-
obj.hobbies.[:] → {„name“ : „Soccer“, „id“ : 0}
-
obj.hobbies.name → [„Coding“, „Soccer“, „Automating Workflows“]
-
obj.hobbies.name[-:] → „Automating Workflows“
4.2. Interpolation Policy
Interpolation can be configured through the JVM environment.
The policies define how the interpolation should behave in specific situations.
4.2.1. Error Policy
These policies regulate how the interpolations shall behave when an error occurs during the process.
They can be configured globally either through setting de.asap.pak.policy.interpolation.error environment with one of the policies below, or by calling the InterpolationErrorPolicy.activate() method of the framework.
| Policy Name | Behaviour |
|---|---|
|
STRICT |
When an exception occurs, the exception will be rethrown. |
|
LOOSE |
When an exception occurs, the interpolation is canceled, and the value with the interpolation is used without resolving the interpolation. |
4.2.2. Guard Policy
These policies regulate which interpolations should be resolved.
The decision is done by a guard which only lets interpolation be processed that have an allowed source.
This can be an advantage when a tool produces an interpolation string, which shouldn’t be interpolated.
They can be configured globally either through setting de.asap.pak.policy.interpolation.guard environment with one of the policies below, or by calling the InterpolationGuardPolicy.activate() method of the framework.
| Policy Name | Behaviour |
|---|---|
|
ALL |
All interpolations encountered are resolved (as it was with version 1.7.x and before) |
|
CONSTANTS |
Only interpolations that are defined as part of a constant mapping or the expression language of the gateway paths are resolved. |
|
NONE |
No interpolation is resolved. |
5. JSONata usage
In addition to basic interpolations, as seen in previous examples,
it is also possible to use the query (and transformation) language JSONata.
This enables many features, like basic string methods, simple arithmetics and boolean or comparison functions,
but also more advanced functions, like sorting, grouping, and filtering as well as functional programming and regular expressions.
For a detailed explanation of JSONata and all provided features click here.
To demonstrate a few possibilities, consider the following example:
This JSON, stored under „Account“ in the datastore, could for example be the result of another command or an api query.
JSONata can then extract or calculate specific values, that might be needed later in the workflow.
{
"Account Name":"John Doe",
"Order":[
{
"OrderID":"order103",
"Product":[
{
"Product Name":"Bowler Hat",
"ProductID":858383,
"Description":{
"Colour":"Purple",
"Width":300,
"Height":200,
"Depth":210
},
"Price":34.45,
"Quantity":2
}
]
},
{
"OrderID":"order104",
"Product":[
{
"Product Name":"Bowler Hat",
"ProductID":858383,
"Description":{
"Colour":"Yellow",
"Width":300,
"Height":200,
"Depth":210
},
"Price":34.45,
"Quantity":4
},
{
"ProductID":345664,
"Product Name":"Cloak",
"Description":{
"Colour":"Black",
"Weight":42
},
"Price":107.99,
"Quantity":1
}
]
}
]
}-
We might need to collect all listed prices to calculate the taxes on each article.
The list of prices could be achieved with the following interpolation:
${Account.**.Price}→ [34.45, 34.45, 107.99] -
To know how much the whole order costs, we can calculate the sum of the total order with the following:
${Account.$sum(Account.Order.Product.(Price * Quantity))}→ 314.69 -
To check that all orders are valid, we can check for a quantity greater than 0:
${Account.$boolean($map(Account.Order.Product.Quantity, function($v) { $v > 0}))}→ true -
To create an object that contains all orders and their number of articles:
${Account.{"allOrders": Account.Order.{"orderID": OrderID,"articles": $sum(Product.Quantity)}}}→
{
"allOrders": [
{
"orderID": "order103",
"articles": 2
},
{
"orderID": "order104",
"articles": 5
}
]
}
6. Escaping Interpolation
To escape a string that should be taken as it is, even if it contains the interpolation syntax ${…},
use a backquote directly in front of the dollar sign.
With `${someVar} the output will be „${someVar}“ and not the interpolated value behind someVar.
To actually use the character of the backquote, escape it with another backquote.
In other words, a double backquote puts a single backqoute in front of an interpolated value.
So ``${test} will result in „`Hello World„, if the variable „test“ contains the value „Hello World“.