powered by ASAP

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.

2. Prerequisites

  • Roughly 10 minutes

  • Basic understanding of Mappings

  • The PAK Bpmn Editor ( Download )

  • The PAK Workflow Executor ( Download )

3. Commands to Use

write value cmd
Figure 1. The Write Value command

Command that take an input value and simply writes it to the datastore.

simple ok cmd
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.

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.

json workflow
Figure 3. Simple Workflow to demonstrate JSON interpolation
{
    "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 and create a constant mapping on messageText containing ${writtenValue.name} (Fig 4).

json mapping simple
Figure 4. Json Path Mapping
json mapping simple result
Figure 5. Json Path Mapping Result

After running the workflow in the PAK Workflow Executor (Download) we get the desired result as shown in Fig 5.

Of course, we have the freedom to interpolate how we desire. For example, we could also extract the age into the same string by mapping messageText to Name: ${writtenValue.name} | Age: ${writtenValue.age} (Fig 6) like shown below.

json mapping simple 2
Figure 6. Json Path Mapping 2
json mapping simple 2 result
Figure 7. Json Path Mapping 2 Result

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. This can be done by simply mapping messageText to ${writtenValue.hobbies.name} (Fig 8).

json array mapping
Figure 8. Json Array Mapping
json array mapping result
Figure 9. Json Array Mapping Result

To select a specific item from the list we can specify an index like writtenValue.hobbies[1] which will result in:

json array mapping 2
Figure 10. Json Array Mapping Result 2
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.

env workflow
Figure 11. Simple Workflow to demonstrate environmental interpolation
java mapping
Figure 12. Java Variable Mapping

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 as shown in Fig 12. After running the workflow we can see that our mapping was successfully replaced. (Fig 14)

env mapping
Figure 13. Environment Variable Mapping

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 analogous. (Fig 13)

java mapping result
Figure 14. Environmental Interpolation Result