How to Define and Use Basic Mappings
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.
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:
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“).
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.
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 this command does not require any additional data to function. However, we still want to modify the optional descriptiveText input as this specific key is telling the users about what they need to do.
Figure 4. Create new mapping
|
|
In order to provide the mapping we first left click the Simple Text Input (Fig 4. 1) and hit the Add Input Mapping button or the plus sign on the right sight of Input (Fig 4. 2). Select descriptiveText from the key dropdown (Fig 5.) and press the Constant Mapping button (Fig 4. 4) and type the desired description (Fig 4. 5), in our case „Input your text here“. For mandatory keys this should resolve any dataflow analysis warning about missing or empty keys.
|
To ensure correct data transportation, make sure that your inputs conform to the JSON format. For example
|
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 <a href="#3_2_workflow_purpose“>3.2 we want the workflow to compare the users input with „Hello World“, so for inputA we can just repeat the steps from above and put „Hello World“ as the desired value.
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 somehow reference this key in the Check Equals command.
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.
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, clicking on the Add Output Mapping button or the plus sign on the right of Output (Fig 4. 2), selecting the output field result (Fig 9. 1) and specifying the customized key in the text field (Fig 9. 2). In this case logOutput.
| If the defined mapping value of that key is left empty, you will get a warning and it will be automatically filled with the name of the key, in this case „result“. |
5. Testing the Workflow
Save the workflow to a location of your choice and open the resulting .bpmn file in the PAK Workflow Executor.
Figure 10. Load the workflow
|
Figure 11. Run the workflow
|
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.