1. What You Will Learn

In this workflow we will learn how to use the datastore in our workflows and use the datastore-JSON to configure our workflows.

This guide will build up on this guide: How to build your first PAK Workflow.

2. Prerequisites

To complete this guide you need:

3. What Is the Datastore

The datastore is our storage for values you gained during processing a command. We can use this values to execute other commands.

4. When to use Datastore

In the BPMN Editor Application the Datastore acts like a “global” store for values which behave like constants.

There are following use-cases why / when you should use the Datastore:

  • you have a constant value which does not change and is consumed by multiple commands.

  • you want to use the same workflow with a different parametrization .

5. How to Use the Datastore

We can add values to the datastore either over the BPMN editor, or by editing the JSON.

5.1. Edit the Datastore in the BPMN Editor

After we opened a new BPMN file in the editor, we will see next to the Dataflow Analysis register card the Datastore (1) register card. There we have the option to add a new entry by clicking on the “+”-Button (2). Now, we have to give our entry a name. Let’s try it with “Testkey” (3). In the value we will write “Testvalue” (4). After that click on Save (5) in the datastore and then save the workflow.

Editor Datastore
Figure 1. Datastore in the BPMN editor

5.2. Edit the Datastore in the JSON File

With every BPMN a new JSON file will be created with the same filename. So, let’s have a look into the JSON file. It is located in the same directory as the BPMN. We navigate to that directory and open the JSON file with any text editor you like. We should get following JSON.

    "key": "Testkey",
    "value": "Testvalue"

Now we want to change the value Text to “Hello World”. After changing the text, we save the JSON File and go back to our BPMN editor. In the editor we have to reload the changes. So we click on the Load button and select our JSON file. After reloading we can see the changed text in the datastore register.

5.3. Use Datastore Variables in Commands

To use our datastore in a BPMN we will create a simple BPMN with the Simple Ok command. This command is a Human Task, where the user gets a Message and have to accept by clicking on an Ok button.

The command needs two inputs. A descriptive text, which is like a headline for the command. And the message text. As descriptive text we will use a constant text. For this case we add the descriptiveText variable in the property window and type something like “Here is your text!”. After that, we add the messageText variable. Because we want our datastore variable, we have to select Key Mapping (1). Below that option the Datastore Key dropdown menu (2) appears, and we can see all datastore keys in our datastore. Currently, there is just our key. Now we can select the key and save the workflow.

Editor DatastoreWorkflow
Figure 2. Datastore Mapping

We can now execute the workflow on an executor app and see the human task with our description, the “Hello World” message and the OK-button.

If you don’t know how to use the executor, you should read the TODO: Insert link to app how to.

5.4. Save Outputs in Datastore Variables

Now we want to extend our workflow. It should be able to say “Hello World to ” and then append our name to the text. The workflow doesn’t know our name, so we have to tell it.

For this we will add a new command before our Simple Ok command. We can use the Simple Text Input command to type in our name. For this we have to delete the connection between the start node and the Simple Ok command. After that, we place the Simple Text Input (1) command between these both and connect the start node with our Simple Text Input command and connect this command with the Simple Ok command.

We can now define the variables for the Simple Text Input command. Again, we need a descriptive text (2). Maybe something like “Enter your name”. We also have the option to enter a default text (3) to the text input field in the human task. Here, we can use simply “Name”. To reuse our text input, we should also define a custom output key, which we can use in other commands. Something like “NameKey” (4) would fit.

Editor DatastoreWorkflowExtended
Figure 3. Define output variables

The key “NameKey” is now available in our datastore, although we have not defined it. It is added internally.

To check this, we can go to our Simple Ok command and delete the previous Datastore Key entry in the “messageText” property. Now we can see both keys, the “Testkey” and the “NameKey”, in the dropdown menu.

5.5. Use Datastore Interpolation in Commands

Unfortunately we want a combination of both keys for our workflow, but on the dropdown we can just use a single key. For this we can use interpolation. With this feature we can insert values of the datastore in constant mappings. Because it’s in a constant mapping, we have to select Constant Mapping (1). Now we can use our key in this mapping with the “$” sign and also combine this key with other keys or constants like strings and numbers. In our case we just need our both datastore variables. So we can simply write ${Testkey} ${NameKey} (2) to the constant mapping field.

Editor WorkflowInterpolation
Figure 4. Interpolation in constant mapping

After saving the BPMN we can run the workflow again. We have to enter our name and confirm. After that we get our “Hello World Name” message with our customized name.

6. Summary

In this tutorial we learned something about human tasks and the datastore. We are now able to use the datastore for exchanging data between commands and configure the workflow with the JSON file. We are also able to interact with the user over the human tasks.