1. What you will learn

After finishing this tutorial you will have a basic overview of what mappings are, why they are needed and how to use them.

2. Prerequisites

To complete this guide you will need:

  • Roughly 10 minutes

  • Basic understanding of Workflows

  • The PAK Bpmn Editor ( Download )

  • The PAK Workflow Executor ( Download )

3. Data Transportation in PAK

In order to demonstrate the usage of mappings, let’s first set up a simple workflow in the Bpmn Editor:

basic workflow
Figure 1. Blueprint of the workflow used to demonstrate mappings

3.1. Which Commands Did We Use?

  • Simple Text Input: Prompts the user with a field to enter a text

  • Check Equals: Checks if two inputs are the same

  • Log Value: Prints a value on the screen

3.2. What Do We Want to Achieve?

The workflow is currently only an enumeration of commands with no real meaning, so let’s give it just that. We want the workflow to take a user input, check if that input is “Hello World” and print the result.

3.3. How Do We Achieve That?

All data in PAK passes the so called datastore. The datastore can essentially be seen as a collection of key-value pairs. Assuming the user types “Hello World” in the text prompt, the datastore would contain a pair of the form (outputText → “Hello World”).

command output keys
Figure 2. Retrieving a commands generated keys

The keys which a command generates can be retrieved by hovering over the respective box in the editor. All generated keys will be listed under Output. Respectively, all keys that a command consumes are to be found under Input.

There might also be the case that a command does not consume and/or generate any keys

Not all parameters are necessary for a command to run, the Dataflow Analysis tab of the Bpmn Editor informs us about the minimum keys required for the workflow to be locked and loaded.

dataflow analysis
Figure 3. The Dataflow Analysis tab

4. Basic Mappings

As the reasoning behind mappings might be hard to grasp, let’s demonstrate them in our example. As you can see, our workflow currently misses 4 datastore entries. We can satisfy those entries by providing the respective command with a mapping to fill the gap.

In general there are two kinds of mappings, which will be discussed in more detail below.

  • Constant Mapping: Provides a hard-coded value for the key in question

  • Key/Datastore Mapping: Provides a key to look up in the datastore.

4.1. Constant Mapping

The first command we’ll look into is Simple Text Input. When comparing the inputs with the warnings in the Dataflow Analysis tab, we can see that the key descriptiveText is missing. According to its description it merely functions as an explanation on what the user has to do.

provide mapping 1
Figure 4. Create new mapping
provide mapping 2
Figure 5. Select key to map
provide mapping 3
Figure 6. Provide constant mapping

In order to provide the mapping we first left click the Simple Text Input (Fig 4. 1) and hit the plus sign (Fig 4. 2). Check the box for Constant Mapping, select descriptiveText from the resulting combobox (Fig 5.), select Constant Mapping (Fig 4. 4) and type the desired description (Fig 4. 5), in our case “Input your text here”. As you can see, the key descriptiveText vanished in the Dataflow Analysis tab, indicating that we provided the needed value.

To ensure correct data transportation, make sure that your inputs conform to the JSON format. For example

  • To supply an empty text, enter “”

  • To supply “”, enter “\”\””

create equals mappings
Figure 7. Key generated by the Check Equals command

Let’s look at the Check Equals command next. By hovering over the command we can see that it needs two inputs, namely inputA and inputB. As mentioned in

inputB should contain the value that was generated as output by the Simple Text Input. Thus, in order to transfer the user input to field inputB of the Check Equals command use the Key Mapping, which is described in the following.

4.2. Key/Datastore Mapping

Key mappings define a binding between an input parameter and a value residing in the datastore. Recalling 3.3, we found out that Simple Text Input writes a pair with the key outputText to the datastore. We now need to reference this key in the Check Equals command somehow.

provide mapping 4
Figure 8. Provide datastore mapping (builds upon Fig 6.)

In order to do so, simply select Key Mapping instead of Constant Mapping (Fig 8. 4) and select the outputText-key (Fig 8. 5). This essentially means that instead of providing a hard-coded value for this input it will be fetched dynamically while the workflow is running. The key inputB is now mapped to outputText and will be replaced by it.

To print the result of our comparison we can either repeat the steps above and map logOutput of Log Value to result or map the output key of Check Equals as described below.

provide mapping 5
Figure 9. Provide write key mapping

With the Key Mapping you also have the possibility to change a parameter name of a command. This way you can define a customized key for the datastore and create a better overview in a larger workflow. In our example we can achieve this by clicking the command Check Equals, selecting the output field result (Fig 9. 1) and Key Mapping (Fig 9. 2) and specifying the customized key in the text field (Fig 9. 3; here “logOutput”).

5. Testing the Workflow

Save the workflow to a location of your choice and open the resulting .bpmn file in the PAK Workflow Executor.

testing 1
Figure 10. Load the workflow
testing 2
Figure 11. Run the workflow
testing 3
Figure 12. Validate results

The analysis should yield no errors, and you can simply run the workflow. As you can see you will be prompted to enter a text with the description we provided above. After providing the correct input (in our case “Hello World”), true will be printed to the console.