Initialize Variables

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 to initialize case or process variables with certain values when executed. Common use cases include:

• Setting default values for variables that are expected by forms or downstream tasks, ensuring they exist with the proper type before being used.
• Defining the structure of complex JSON variables, such as creating a nested JSON object that maps to a form with grouped fields (e.g. a person variable with nested address properties).
• Mapping and transforming data from a previous task (e.g. filtering and restructuring the response of an HTTP task into the specific variables needed by subsequent tasks).
• Copying variable values from one variable to another using the Variable value type.

The task supports primitive types (Boolean, Double, Integer, Long, String), JSON Objects, JSON Arrays, variable references, and arbitrary expressions for advanced scenarios. When placed on the canvas, two properties specific to this task are shown: Init variables (which opens a configuration popup) and Overwrite if existing (which controls whether existing variables are replaced).

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 case/process 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 CMMN case to get familiar with the Initialize variables task. Drop both an Initialize variables and a Human Task onto the canvas inside a stage:

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 not 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 human 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 case model. When now starting a new case instance and opening the human 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 CMMN case model now gets an additional task, which we'll call Show Data. We'll rename the original human 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 Gather Data task. For the street, number and city, we need to use {{person.address.x}}:

Associate the same form with the Show Data task. In the first human 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 case 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 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 CMMN case 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 human 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 case instance. When opening the Show Data human 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 human 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:

Properties

General

Attribute	Type	Description	Category
Model Id	Text	Model Id identifies the element within the process model.	The model id, name and documentation properties can be found on any element. They are used respectively to uniquely identify the initialize variables task, to give it a user-friendly name and to add a free-form description.
Name	Text	The name of the element. This is the name displayed in the diagram.
Documentation	Multiline Text	The documentation attribute additionally adds a description to the component.
Init variables	List	Specify all variables to be set using this service task. Specify the target object for each of the variables (even with an expression), specify the name of the variable to set and finally the variable value itself to be set (can also be an expression).	Specify the variables that will be initialized when this task is executed. The Target column is optional. It can be used when defining a complex variable JSON structure 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. The Value field allows to set the value of the variable statically or using a back-end expression.
Overwrite if existing	Boolean	If set to true, variables which are already existing will be overwritten, if set to false, only non-existent variable values will be set and existing ones will not be touched.	Check the Overwrite if existing to overwrite any existing variable defined in the variable mapping that existed before this task and has the same variable name.

AI

Attribute	Type	Description	Category
AI Activated	Boolean	Make this element available within the context of an orchestrator agent.	These settings can be used when an orchestrator agent is linked to the case model. The flag AI Activated determines whether or not the agent will look at this particular plan item when evaluating which ones should be activated. The Activation type can be set to suggestion, in which case the agent will make a suggestion to the user (e.g. in the chat) if it deems this plan item needs to be activated, based on the case instance context. When using automatic, the agent will start the plan item itself, without user input. Lastly, the AI Instruction field allows to add specific instructions towards the agent. These will be added to the prompts when the agent is analyzing the current state.
Activation type	Selection: Suggestion Automatic	The type determines how this element will be activated by an orchestrator agent. Use 'Suggestion' when the agent should give advices and use 'Automatic' if the agent is allowed to complete elements itself without user interaction.
AI instruction	TextArea	An AI instruction that provides additional instructions to the orchestrator agent. The more details here, the more applicable the responses will be.
AI activation permission groups	Group Selection	Define the groups which have access to the AI activated suggestions.

Control

Attribute	Type	Description	Category
Required	Boolean	Select this option to mark the element as required (exclamation mark decorator). Required plan items must be either in the status COMPLETED, TERMINATED, or DISABLED in order for their parent stage to complete.	Check this option to mark this initialize variables task as required, which means that it needs to be in a terminal state in order for its parent to complete. Visually, the service task will get an exclamation mark icon. Required plan items must be in a terminal state (such as completed or terminated) in order for their parent stage to complete.
Completion neutral	Boolean	Completion neutral influences the plan item's parent stage completes. Plan items in the state AVAILABLE may prevent the parent stage (or case) from automatically completing. By checking this property, the plan item will behave neutral with respect to the completion of the parent container.	Completion neutral influences the plan item's parent stage completion. Normally, plan item instances in the state available may prevent the parent stage (or case) from automatically completing. By checking this property, the initialize variables task plan item instance will behave neutral with respect to the completion of the parent container (i.e. it will not stop the completion).
Manual activation	Boolean	Select this option to mark the element to have Manual activation (right arrow 'play' decorator). Plan items with Manual activation move from state AVAILABLE to state ENABLED once they trigger. A plan item in state ENABLED exposes an action button that allows the user to manually start the plan item.	A manual activated initialize variables task is not automatically activated when its parent stage becomes active. Instead, the corresponding plan item instance will be in the available state, until the user manually uses the action to activate it, at which point the variables are initialized.
Manual activation name	Text	Define the name to be used for the manual activation trigger.
Manual activation icon	Icon	Define the icon to be used for the manual activation trigger.
Manual activation priority	Integer	The priority for the Manual activation action
Manual activation permission groups	Group Selection	Define the groups which have access to the manual activation trigger.	Advanced configuration for manual activation. The permission groups allow to define which groups and the permissions users allow to define which users can use the action to manually activate the init variables task plan item instance.
Manual activation permission users	User Selection	Define the users which have access to the manual activation trigger.
Manual activation channels	Text	Define a list of channels to expose the manual activation action.
Start form	Reference	An optional form shown when the event listener is manually activated.	The form that is shown when the action to manual activate the initialize variables task is used. If there is no form, the task will immediately be activated.
In same deployment	Boolean	Set it to true if the referenced definition should be referenced from within the same app deployment. Set it to false to always use the newest definition.	The Same deployment flag is used to indicate that the manual activation form model that is used is part of the same app deployment package as where the current CMMN model is in. If unchecked, the latest version is used which can come from an app that is deployed at a later point in time.
Validate start form fields (server-side)	Boolean	If the start form is submitted and validate form fields expression evaluates to true, form fields are validated on the BE side according to the form model restrictions.	If the form is submitted and the flag or expression on the left-hand side evaluate to true, the form fields will be validated on the server-side according to the form model restrictions.

Repetition

Attribute	Type	Description	Category
Repetition	Boolean	Select this option to mark the element as repeatable (fencemark decorator). Repeatable plan items may exist more than once at run-time, each having their own life-cycle.	When repeatable multiple plan item instances of this task will be created, executing the variable initialization multiple times. The use cases for this are rather limited, as most can be configured in the variable mapping itself. The repetition can be an expression, and new instances are created as long as the expression resolves to true. This can be limited using the Max instance count. The Repetition counter variable is a local variable with a value incremented by one for each new plan item instance created. Alternatively, a Collection variable can be passed which leads to a plan item instance per element in the collection. The element can be captured in a variable using the Element variable and its index in the collection in the Element index variable.
Repetition counter variable	Text	Name of the repetition counter variable.
Don't create repetition counter variable	Boolean	Enable this flag to prevent the creation of the repetition counter variable. When a variable aggregation is defined, this flag will be ignored and a repetition counter variable will be created.
Max instance count	Selection: unlimited one	Defines the maximum number of instances for repetition. Note that this does not mean there can be only one instance ever in the lifetime of a case instance, this will limit the instances each time when the repetition is evaluated (for example when an entry sentry evaluates to true to re-enter a stage or plan item).
Collection variable	Text	Variable to be used as the collection for the repetition.
Element variable	Text	Variable that will be used to store the current item value for the repetition.
Element index variable	Text	Variable that will be used to store the current index value for the repetition.
Variable Aggregations	List		When having multiple instances of this task, there could be a need to create an aggregation of the variables created and/or updated in each instance, although the use cases for this are rather limited as most can be done through the variable mapping itself.

Advanced

Execution

Attribute	Type	Description	Category
Impact on parent completion	Selection: default ignore ignore if available ignore if available or enabled ignore after first completion ignore after first completion if available or enabled	Defines how the plan item is used when the parent completion evaluation is executed.	Normally, a parent stage completes when it has no active child plan item instances and all such instances are in a terminal state. Using auto complete, this can be changed to only look at the plan items marked as required. Using the Parent completion here, this behavior can be further specified: default will be as described above while ignore means that this initialize variables task isn't taking into account when checking if the parent stage completes. The other options allow for even finer-grained control to determine when to ignore this service task with regards to parent stage completion.
Asynchronous	Boolean	When enabled, the behavior of the plan item will be executed as an asynchronous job. This will happen when the plan item transitions to the ACTIVE state. During the execution of the behavior, the plan item will be set to an intermediate ASYNC_ACTIVE state. Please refer to the documentation for more details.	When marking this service task as asynchronous, the variable initialization will be executed asynchronously in the background. This is useful for example to not block the UI of a user, in case of longer running logic. Choose exclusive to avoid other asynchronous steps of this process instance to run at the same time. When Leave asynchronously is enabled, the activity will be left as an asynchronous job. This means that the activity is ended asynchronously.
Exclusive	Boolean	Determines whether the plan item is run as an exclusive job. An exclusive job makes sure that no other asynchronous exclusive plan items within the same case instance are performed at the same time. This helps to prevent failing jobs in concurrent scenarios.
Leave asynchronously	Boolean	When enabled, the leaving of the plan item will be executed as an asynchronous job. This will happen when the plan item transitions moved out of the ACTIVE state. During the execution of the behavior, the plan item will be set to an intermediate ASYNC_ACTIVE_LEAVE state. Please refer to the documentation for more details.
Leave exclusive	Boolean	Determines whether the activity should leave as an exclusive job. An exclusive job makes sure that no other asynchronous exclusive activities within the same process are performed at the same time. This helps to prevent failing jobs in concurrent scenarios.
Job Category	Text	When set, the underlying generated job will have a Job Category, which will be executed only by Application Servers, where the Case Engine has enabledJobCategories set to this category.
Include in history	Boolean	When the history level is set to "instance" or "task" level with this property it can be configured if this plan item instance should be included in the historic plan item instance data.	The Include in history flag can be used to store the historical entry of this initialize variables task when running with a history level that normally would not store the execution of the plan item. Note that this flag has no effect when running with history level 'none'.

Listeners

Attribute	Type	Description	Category
Lifecycle listeners	List	Allows you to define lifecycle listeners for a plan item. Lifecycle listeners allow you to execute an expression, a delegate expression or a class when a plan item transitions from one state to another.	With lifecycle listeners it is possible to react to state changes of the initialize variables task. Lifecycle listeners allow you to execute an expression, a delegate expression or a class when the service task transitions from one state to another.

Reactivation

Attribute	Type	Description	Category
Direct activation condition	Boolean	Condition that expresses if the plan item should be directly activated when a case instance is reactivated.	Case reactivation is the the ability to reopen a finished case instance and continue with its execution. Case reactivation needs to be modeled using a reactivation listener and specific behavior can be configured for each plan item in the case model. An initialize variables task is very useful in this context, as it allows to set or change new or exiting variables for the reactivated case instance. The Direct Activation Condition is the first condition to be evaluated during case reactivation. If checked or if there is an expression evaluating to true, the initialize variables task immediately gets activated, regardless of any entry sentry or condition which might be necessary to restart at a certain state of the case (e.g. a stage). The Ignore Condition, if checked or if there is an expression evaluating to true, means that the initialize variables task is ignored on reactivation. The Default Condition only gets evaluated, if the previous ones are either not checked or evaluated to false. If so, the initialize variables task behaves like a regular one as if the case instance was started from scratch. This means that any necessary entry sentry is considered and evaluated and the engine proceeds as normal. Please check the Flowable documentation for more details.
Ignore condition	Boolean	Condition that expresses if the plan item should be ignored when a case instance is reactivated.
Default condition	Boolean	Condition that expresses if the plan item should trigger when a case instance is reactivated.

Visual

Attribute	Type	Description	Category
Font size	Selection: 8 9 10 11 12 14 18 20 24 36 48 72	The font size of the element in the diagram.	Visual properties that determine how the initialize variables task is shown in the diagram. This has no impact on the runtime execution.
Font weight	Selection: Normal Bold	The font weight of the element in the diagram.
Font style	Selection: Normal Italic	The font style of the element in the diagram.
Font color	Color	The font color of the element in the diagram.
Background color	Color	The background color of the element in the diagram.
Border color	Color	The border color of the element in the diagram.

List Attribute Details

Init variables

Attribute	Type	Description
Target Variable	Text with suggestions: parent root
Name	Text	The name of the element. This is the name displayed in the diagram.
valueType	Selection: Integer Long Double Instant String Expression Boolean Big integer Big decimal New JSON Object New JSON Array
Value	Text	Value.

Variable Aggregations

Attribute	Type	Description
Target (Variable / Expression)	Text	The name of the target variable or an expression that gives the variable name
Type	Selection: Default Custom	The audit log type.
Delegate Expression	Text	Delegate Expression to be executed when the task is activated. A delegate expression must resolve to a Java object, for instance a Spring bean. The object's class must implement either PlanItemJavaDelegate or CmmnActivityBehavior.
Class	String	Fully qualified classname of a class to be invoked when executing the task. The class must implement either PlanItemJavaDelegate or CmmnActivityBehavior.
Target variable creation	Selection: Default Create overview variable Store as transient variable
Variable Definitions	BasicFormList

Variable Definitions

Attribute	Type	Description
Source (Variable / Expression)	Text	The name of the source variable or an expression that provides the value
Target (Variable / Expression)	Text	The name of the target variable or an expression that gives the variable name

Lifecycle listeners

Attribute	Type	Description
Source state	Selection: Any Available Active Enabled Disabled Completed Failed Suspended Closed Terminated Waiting for repetition Async active Async active leave
Target state	Selection: Any Available Active Enabled Disabled Completed Failed Suspended Closed Terminated Waiting for repetition Async active Async active leave
Class	Text	Fully qualified classname of a class to be invoked when executing the task. The class must implement either PlanItemJavaDelegate or CmmnActivityBehavior.
Expression	Text	JUEL Expression to be executed when the task is started. Expressions allow you to interact with the backend by calling services, making calculations etc. You can find more information about expressions in the documentation.
Delegate expression	Text