How to Define and Use Basic Mappings
After finishing this tutorial you will have a basic overview of what mappings are, why they are needed and how to use them.
In order to demonstrate the usage of mappings, let’s first set up a simple workflow in the Bpmn Editor:
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
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.
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.
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.
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.
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 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
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.
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.
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, 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“).
|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“.
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.