Initialize Variables Task

Target audience: Modelers

Introduction

The Initialize Variables task is an activity for Flowable Work that is available in the BPMN and CMMN palette in Flowable Design. It can be found under the Flowable Work Activities group in the palette:

The purpose of this task is clear from the name: it allows to initialize process or case variables with certain values when executed. The task can also be used to prepare the structure of more complex variables (like JSON variables).

When dropping the task on the canvas, two properties specific to this task type are shown in the right-hand property panel: Init variables and Overwrite if existing:

Clicking the Init variables property will open a popup window that allows to set and configure various variables:

The Overwrite if existing checkbox, when checked, determines whether or not to overwrite any existing variable with the variable values set in this task. The default is true: existing variables will be overwritten.

Configuration

The Init variables popup has a tabular format: each row corresponds with a variable (or, as we'll see later, the definition of the structure of a complex variable).

The icons on the left hand-side can be used to respectively remove, move up or move down that row. Moving the rows up and down doesn't make a difference for regular variables, but the order is important for complex variables as the rows are read from top to bottom at runtime.

The Target column is optional. It can be used when defining a complex variable JSON structure (see later) or with values root or parent. Setting root or parent will set the variable not on the local instance, but on the parent or root instance in a nested hierarchy of process/case instances.

The name column is used to determine the name of the variable and is mandatory.

The Value Type column is used to determine the type of the variable, which is important as it switches the input field type depending on the chosen type (for example a date picker when selecting Date):

Current supported value types are:

• Primitive types that set a variable with the corresponding type: Boolean, Double, Integer, Long and String.
• JSON Array/Object for definiting JSON variable values or structures. More about it later.
• Variable: Used to copy the value from another value.

The Value column allows to set the actual value and the input field type for filling in the value depends on the selected Value type, as shown above.

Next to the Value input field is a lightning icon. When clicked, the current row changes:

• The Value field becomes an input text area that allows to write an abitrary expression.
• The Value type dropdown disappears, as the type will now implicitely be determined by the result of the expression.

This option is meant for advanced variable initializations and is used to write potentially complex expressions for use cases that cannot be covered by the default configuration options. As this is a back-end expression, all the usual beans are available.

Basic Example

Let's build a simple BPMN process to get familiar with the Initialize variables task. Drop both an Initialize variables and User Task to the canvas and connect them with sequence flow:

For the Init variables property, let's add some variables:

• firstName (String)
• lastName (String)
• married (Boolean)
• street (String)
• number (Integer)
• city (String)

Add some random values for each variable. You'll notice that it's for example ot possible to write regular text in the number field, because the value type is set to Integer.

note

The use case here is not necessarily to set values of variables hard-coded to a given value (that's not often useful). The main purpose is to 1) make sure the required variables exist with the proper type and 2) (optionally) that default values for them are provided.

For the user task, create a form that binds the values to the variables set in the Init variables (for example the field with label First Name is bound to value {{firstName}}):

Publish this process model. When now starting a new process instance and opening the user task, we can see the values have indeed correctly been initialized:

When running with Flowable Inspect enabled, you can see each row in the popup above corresponds with one variable created at runtime:

JSON Variable Example

Another use case for the Initialize variables task is to define the structure of more complex JSON variables.

To demonstrate this, let's tweak the model from the previous section. The BPMN model now gets an additional task, which we'll call Show Data. We'll rename the original user task to Gather Data:

The main difference with the basic example is that we don't want to store one variable for each form field. Instead, we'd like to use the JSON variable type to stores all information in one variable. Change the Init variables property as follows:

• Add a new row with name person at the top with value type JSON Object. This will create a JSON variable with name person. The next rows will now be used to define the structure of the person variable.
• Add person to all other fields in the target column. As person is a JSON object, setting the target in this way instructs the engine to put those fields on the json object at runtime.
• Add a prefix address. to the street, number and city variables. This way, we automatically create a nested json object within the person variable.
• Remove all values.

After doing this, the configuration should look as follows:

The goal is to have a JSON variable named person with following structure:

{
  "firstName": "a",
  "lastName": "b",
  "married": false,
  "address": {
    "street": "c",
    "city": "d",
    "number": 0
  }
}

note

We're not setting any default values now (but we could, if we wanted to). The main purpose here is defining the structure of the JSON variable.

As we're using a JSON variable now, we need to bind form fields using {{person.x}} now in the form of the the Gather Data task. For the streetm number and city, we need to use {{person.address.x}}:

Associate the same form with the Show Data task. In the first user task form we will fill in the fields and in the second task we'll view them.

Publish this new model and start a new instance. None of the form fields of the Gather Data task will have values set (as no value was set above):

Fill in some values for the various fields and click the Complete button. Select the new Show Data task.

You'll see that the values from the previous form are shown:

When running with Flowable Inspect enabled, you can see the difference with the basic example clearly; instead of having multiple variables, theres only one person variable:

Clicking the edit icon, shows that all data is now stored as a JSON variable with nested properties:

Mapping Data Example

Another use case for the Initialize variables task is to map data into a structure or format that is more suitable for tasks that follow after it.

Let's assume we want to fetch data from a HTTP REST service and store some parts (but not all) of the response need to be stored as variables. Such an API can be locally mocked by using for example Mockoon:

This service response data looks as follows:

{
  "firstName" : "John",
  "lastName": "Doe",
  "gender": "M",
  "birthDate": "1/1/2001",
  "other": {
    "married": true,
    "address": {  
      "street": "Randomstreet",
      "number": "123",
      "city": "Doeville"
    }
  }
}

The response returns more data than needed, so we'll use the Initialize variables task to filter the data and put it in the format we want. The BPMN process model now looks as follows:

Configure the HTTP Task:

• Request method: GET
• Request URL: http://localhost:9999/persons/123 (same as the mocked api URL)
• Save response as JSON: checked
• Save response as a transient variable: checked

note

The response of the HTTP task is stored as-is as a transient variable. This means that the variable will not be persisted at the end of the database transaction (which typically we don't want: the response might be large and storing it would be bad for performance). The Initialize Variables task will instead determine what gets stored and will use the transient JSON variable as input.

In the Initialize variables configuration we'll map the JSON response to primitive variables:

• firstName gets value type variable and value response.firstName.
• lastName uses an expression ${response.lastName}. There is no specific reason to not use the variable value type here, except for demonstrating the usage of expressions to do the same as with the variable type.
• married gets value type variable and value response.other.married, because it's not mapped from the root, but from the other nested JSON object.
• street, number and city get value type variable and values response.other.address.street, response.other.address.number and response.other.address.city.

The form in the user task simply displays these variables by binding the fields to the variable values (we're again use one variable per field, similar to the basic example):

Deploy this model and start a new instance. When opening the Show Data user task, the data fetched from the HTTP service is now displayed in the form:

When running with Flowable Inspect enabled, we can see that the HTTP response is not stored as a variable (as we marked it as transient) but the variables from the Initialize variables task have been stored:

Advanced

Name expressions

The name column of the Init variables configuration can be an expression. For example ${newVariableName} is valid if newVariableName comes from a form field that was set in a user task form or service task before.

JSON Arrays

Using the JSON Object value type allows to model JSON variables with a complex structure. The JSON Array value type adds the abilities to store lists.

When selecting the JSON Array type, optionally the default size of the array can be configured. Default values can be set by using zero-based indexes (for example by using addresses[0].street ) in the name column and providing a value: