How to use Advanced Mappings (Interpolations)
1. What you will learn
In this tutorial you will learn how to bring mappings to the next level by using PAKs Interpolation to manipulate variables from the datastore.
3. Commands to Use
Figure 1. The Write Value command
Command that take an input value and simply writes it to the datastore. |
Figure 2. The Simple Ok command
Command which simply shows an informational text together with an ok button. |
4. Advanced Mappings
Interpolations are used to extend the functionality of constant mappings. An interpolation can be integrated in any string mapping using the syntax ${interpol} where interpol is of one of the types described below.
| For a complete rundown of the syntax for interpolations, please refer to the syntax reference. |
There is also a Quick Interpolation Tool available:
| 1 | Select the constant mappings |
| 2 | Press the $ symbol to open a list of valid datastore keys |
| 3 | Select an available key from the tools list |
| 4 | The selected key has now a valid interpolation on that key. |
| The Tool can only interpolate regular datastore keys. Interpolations on environment variables or fields of that key must be done manually. |
In order for PAK to recognize the object the expression should be evaluated on, include the subject followed by a dot and your jsonata expression.
4.1. Json Interpolation
In PAK, all data that passes the datastore is transformed to the JSON format. This allows us to perform transformations on stored values via the JSON path syntax.
4.1.1. The Workflow
In order to demonstrate JSON path interpolation we will need a JSON in the datastore that we can perform actions on. So let’s set up a very simple workflow that merely writes a value into the datastore and prints the result.
{
"name" : "Max",
"age" : 33,
"hobbies" : [
{
"name" : "Soccer",
"id" : 0
},
{
"name" : "Coding",
"id" : 1
},
{
"name" : "Automating Workflows",
"id" : 2
}
]
}To use that JSON in our command we create a constant mapping for readValue as described in the previous tutorial.
4.1.2. Json Path Mapping
As you can see, our JSON model represents a person that has a name, age, and a list of hobbies attached. However, we might only be interested in the persons name. As the JSON will be written by the Write Value command, we can reference it with writtenValue. So in order to extract the name from the JSON data we use JSON pathing (Fig 5).
Figure 5. Json Path Mapping
|
Figure 6. Json Path Mapping Result
|
| 1 | Select the messageText key |
| 2 | Map its constant value to ${writtenValue.name} |
After running the workflow in the PAK Workflow Executor (Download) we get the desired result as shown in Fig 6.
Of course, we have the freedom to interpolate how we desire. For example, we could also extract the age into the same string (Fig 7).
Figure 7. Json Path Mapping 2
|
Figure 8. Json Path Mapping 2 Result
|
| 1 | Select the messageText key |
| 2 | Map its constant value to Name: ${writtenValue.name} | Age: ${writtenValue.age} |
4.1.3. Json Array Mapping
The list of hobbies is not really looking appealing due to each element being a JSON itself. Using JSON array mapping we can extract only the name of the hobbies in our interpolation (Fig 9).
Figure 9. Json Array Mapping
|
Figure 10. Json Array Mapping Result
|
| 1 | Select the messageText key |
| 2 | Map its constant value to ${writtenValue.hobbies.name} |
To select a specific item from the list we can specify an index like writtenValue.hobbies[1] which will result in:
| Make sure that the index you are using is withing the bounds of the JSON array |
Alternatively we can specify to extract either the first, or the last value like writtenValue.hobbies[:], respectively writtenValue.hobbies[-:].
4.2. Environmental Interpolation
While you can fetch values from PAKs datastore, sometimes the need arises to acquire values that were not necessarily written, for example the location of the users home directory.
As environmental mappings are not dependent on the datastore, we can simply take the workflow from Fig 3 and omit the Write Value command leaving us with the following workflow.
PAK executes in a Java runtime, enabling us to use variables defined by java. So for this instance we can define our command to use the Java variable user.home.
| 1 | Select the key messageText |
| 2 | Map its constant value to ${java(user.home)} |
After running the workflow we can see that our mapping was successfully replaced. (Fig 15)
Not only can we acquire values from the Java runtime, but also our operating systems environment variables. For example, on a Windows system we can check for the user home using the UserProfile environment variable.
| 1 | Select the key messageText |
| 2 | Map its constant value to ${env(UserProfile)}. |
4.3. Jsonata Interpolation
Since PAK version 1.11.15, interpolation using the JSONata query language is also possible and,
when applicable, will be prioritized over the default json path interpolation.
| You can test your expressions, before plugging them into the application here |
In the example workflow above, we can for example extract a smaller json object containing only the name,
using the following expression, which will evaluate to a smaller object.
Figure 16. Jsonata Mapping
|
Figure 17. Jsonata Mapping Result
|
A more detailed example can be found in the Interpolation Syntax Reference.
4.3.1. Custom Functions
Jsonata also offers the ability to register custom functions, that in our case will be evaluated by the framework. This section provides an overview over all PAK jsonata functions which can be used in your expressions. […] defines optional parameters.
$workspace() ~> String
During initialization, a PAK engine creates a workspace folder, in which most of file creation takes place. This function returns the path to this directory.
| Optional parameters can also be omitted (started from the right), essentially passing an empty value |
$temp_dir([name]) ~> String
Creates a new temporary directory in $workspace(). If name is not given, a random but unique name will be chosen. If name is set, a timestamp will still be appended. This functions returns the path to the created directory.
$temp_file([name],[ext]) ~> String
Creates a new temporary file in $workspace(). If name is not given, a random but unique name will be chosen. If name is set, a timestamp will still be appended. The created file with have the extension ext when set, or no extension when it is not. This functions returns the path to the created file.