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. |