Call Activity

Introduction

info

A Call Activity identifies a point in the Process where a global Process or a Global Task is used. The Call Activity acts as a 'wrapper' for the invocation of a global Process or Global Task within the execution. The activation of a call Activity results in the transfer of control to the called global Process or Global Task.

— BPMN 2.0.2 Standard, 10.3.6, Call Activity

BPMN 2.0 makes a distinction between a regular sub-process, often also called embedded sub-process, and the call activity, which looks very similar. From a conceptual point of view, both call a sub-process when the process execution arrives at the activity.

The difference is that the call activity references a process that is external to the process definition, whereas the sub-process is embedded within the original process definition. The main use case for the call activity is to have a reusable process definition that can be called from multiple other process definitions.

Properties

General

Common

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 call activity, to give the call activity 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	A free-form text that can be used to explain details about the particular element.

Process

Attribute	Type	Description	Category
Process reference	Reference	Reference to a process that will be started when this call activity is executed	Reference to the BPMN process model of which a process instance will be started when this call activity is executed.
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 BPMN process model to be used for starting the new instance is part of the same app deployment package as where the current BPMN 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. The Fallback to default tenant indicates that the deployed BPMN process model will be taken from the default tenant if the BPMN process model is not deployed in the tenant where the current process instance is running in. This is only relevant if Flowable is set up in multi-tenant mode.
Fallback to default tenant	Boolean	Indicates that the new instance will be created with the default tenant if it is not available on the current tenant. This is only relevant if the application runs multiple tenants.
Instance name	Text	Name of the newly created process instance.	The process instance that is started when this call activity is executed can get a custom name by setting the Instance name. The process instance can also get a business key, which is a textual value that can be used to query and find easily the relevant instance. The key typically has a business meaning. If the Inherit business key option is checked, the business key of the current process instance will be copied into the new process instance. If needed, the ID of the newly created process instance can be stored in a variable with the Process ID variable option.
Business key	Text	Business key of the newly created process instance. Can be an expression.
Inherit business key	Boolean	Inherit the business key from the parent process.
Process ID variable	Text	An optional variable that holds the ID of the created process instance.

Variable Mapping

Attribute	Type	Description	Category
In	VariableMapping	An optional input parameter map. Allows the mapping of parameters and variables which will then be available in the newly created instance.
Out	VariableMapping	An optional output parameter map. Allows to store variables of the case back to the parent instance when the child instance completes.
Inherit variables	Boolean	Inherit parent process variables in the newly created instance.	If the 'Inherit variables' option is checked, the child process instance will get a copy of all variables of the current process instance.
Use local scope for out mapping	Boolean	Use local variable scope for out parameters.	If this option is checked, the variables from the process instance of the call activity are copied to the local execution instead of the process instance.

Multi Instance

Multi instance

Attribute	Type	Description	Category
Multi instance type	Selection: None Parallel Sequential	The type of multi-instance: default is 'None' meaning a single instance is created at runtime. Select either 'Parallel' or 'Sequential' if you want multiple instances to be created.	Multi-instance is used to define the repetition of this call activity at runtime. With multi-instance it is possible to start the process instance (and thus everything inside it) multiple times, either sequentially where each instance of the subprocess is executed after the previous or in parallel where the instances are created all at once and exist concurrently. For example, when referencing a collection one instance is created for each element of that collection.
Collection	Text	References a collection variable (for example a JSON array variable) by its name or using an expression that resolves to a collection.
Element variable	Text	The name of the variable where the currently processed element from the multi-instance collection configured above will be stored (for example, 'invoicePosition'). The element can then be accessed through an expression, e.g., ${invoicePosition}.
Element index variable	Text	The name of the variable where the index of the currently processed item from the multi-instance collection will be stored, for example, 'itemIndex'. The index is a number starting with 0 which is increased with every element that is being created. The index can then be accessed through an expression, e.g., ${itemIndex} further on in the process.
Cardinality	Text	A fixed number or an expression that resolved to an integer that controls the number of instances that will be created. This is typically used when there is no collection available or needed.
Completion condition	Text	An expression that should resolve to a boolean value. When evaluating to true, the remaining activity instances will be removed and the process instance will continue.

Variable aggregation

Attribute	Type	Description	Category
Variable Aggregations	List	Define an aggregation. Each element in this list will result in one aggregation variable.	When using multi-instance, there is often a need to create an aggregation of the variables created and/or updated in each instance. With variable aggregation, a JSON variable can be created that after all instances have been completed contains the summary of all the used variables. This is needed because for multi-instance, variables are persisted locally, to avoid clashes on the process instance level. Alternatively, an 'overview' variable can be created while the instances are still unfinished. Each aggregation consists of one or multiple definitions that map instance variables of one instance of the multi-instance to the aggregation variable.

Advanced

Attribute	Type	Description	Category
Optimize for only automatic steps	Boolean	(Advanced setting, only check it if you understand the implications) If checked, this instructs the Flowable engine that the multi-instance only contains automatic tasks and no wait states. In this situation, an asynchronous job is created when the multi-instance activity is entered that keeps checking if all instances are completed and completes the multi-instance. The benefit of this approach is that it is light on resources versus alternatives and doesn't lead to optimistic locking exceptions.	If checked, this instructs the runtime execution engine that the multi-instance only contains automatic tasks and no wait states (like for example a user task). In this situation, one asynchronous job is created when the multi-instance activity is entered that keeps checking if all instances are completed and completes the multi-instance, instead of concurrently trying to complete the instances separately. The benefit of this approach is that it is light on resources, often more performant and doesn't lead to optimistic locking exceptions. This is an advanced setting. Only use it when you fully understand the implications.

Advanced

Execution

Attribute	Type	Description	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 activity instance should be included in the historic activity data.	The Include in history flag can be used to store the historical entry of this call activity when running with a history level that normally would not store the execution of the call activity. Note that this flag has no effect when running with history level 'none'.
Is transaction	Boolean	A BPMN transaction is a set of activities that logically belongs together. Transactions can be cancelled through the Cancel End Event and handled through the Cancel Intermediate Boundary Event.	A BPMN transaction is a set of activities that logically belongs together. Transactions can be cancelled through the Cancel End Event and handled through the Cancel Intermediate Boundary Event. The Is for compensation field can be used to indicate that the subprocess is meant as compensation steps for another activity.
Is for compensation	Boolean	Determines whether the activity can serve as a compensation for another activity.
Asynchronous	Boolean	When enabled, the activity will be started as an asynchronous job. The process state is persisted before this element is executed. Then, the process execution will be resumed asynchroneously. This can be used when the execution an activity takes a long time to return the UI to the user quicker in case the user does not need to see the next step immediately. However, if an error occurs before the following wait state, there will be no direct user feedback. Please refer to the documentation for more details.	When making a call activity asynchronous, the start of the child process instance will be handled asynchronously in the background. 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 activity or process is run 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.
Leave asynchronously	Boolean	When enabled, the activity will be left as an asynchronous job. This means that the activity is ended asynchronously, including end execution listeners. 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 Process Engine has enabledJobCategories set to this category.

Advanced options

Attribute	Type	Description	Category
Data objects	List	Defines the Data Objects of the process or Sub-Process. Each data object will be initialized as a process variable under the defined name.	With data objects, process instance variables can be initialized when process instance for the call activity is executed. Note: these data objects are part of the BPMN specification and are not to be confused with the data object models in Flowable.
Complete asynchronously	Boolean	Executes the completion of the call activity in an exclusive asynchronous job. This is for example useful im combination with parallel multi-instance.	If this option is checked, the completion of the call activity is done asynchronously in the background. This is useful if there is heavy-weight logic attached to the ending of the process instance, for example in an execution listener. Another use case is when using multi-instance with all asynchronous straight-through process instances. Making the completion async in that case will avoid concurrent changes and potential optimistic locking exceptions.
Exception Mappings	List	Define one or more exception mappings to map a technical Java exception to a BPMN error code.	Map technical java exceptions to BPMN error codes that can be caught with a boundary error event.

Listeners

Attribute	Type	Description	Category
Execution listeners	List	Allows invoking custom after certain lifecycle events. Start: Executes after the activity has been started. End: Executes after the activity was completed. Transition: When defined on a sequence flow, executes once the flow is transition is taken.	Execution listeners are used to add logic on certain lifecycle events. Typically it is used to add extra technical logic which shouldn't be visible in the BPMN process model.

Visual

Attribute	Type	Description	Category
Font size	Selection: 8 9 10 11 12 14 18 20 24 36 48 72	Font size.	Visual properties that determine how the call activity is shown in the diagram. This has no impact on the runtime execution.
Font weight	Selection: Normal Bold	Select the style between bold and normal.
Font style	Selection: Normal Italic	Select the style between italic and normal.
Font color	Color	Select a font color.
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

In

Attribute	Type	Description
Source variable	Text	The name of the variable that should be mapped to the target variable
Source Expression	Text	Instead of a variable, an expression can be used to resolve to a value, which is used to map into the target variable.
Target variable	Text	The name of the variable into which the source variable or expression is mapped.

Out

Attribute	Type	Description
Source variable	Text	The name of the variable that should be mapped to the target variable
Source Expression	Text	Instead of a variable, an expression can be used to resolve to a value, which is used to map into the target variable.
Target variable	Text	The name of the variable into which the source variable or expression is mapped.

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 type of aggregation. Use 'default' to use the standard behavior of creating an aggregation JSON variable. Use 'custom' to define a delegate expression that will handle the aggregation. Please see the documentation for more information.
Delegate Expression	Text	Define a delegateExpression that will resolve to an instance of VariableAggregator (for BPMN) or PlanItemVariableAggregator (for CMMN). This instance will then be responsible for aggregating the variables.
Class	String	A class that implements VariableAggregator (for BPMN) or PlanItemVariableAggregator (for CMMN). This instance will then be responsible for aggregating the variables.
Target variable creation	Selection: Default Create overview variable Store as transient variable	Configures the way the aggregation variable is created. The 'Default' option creates the aggregation variable when all instances of the multi-instance have been completed. Use 'Create overview variable' to create a variable at the start of the multi-instance and keep it up to date during multi-instance exeution. Once all the instances are completed it will create a JSON variable in the same way as for Default target variable creation. Use the 'Store as transient variable' option to have the default behavior, but store the resulting aggregation variable transiently.
Variable Definitions	BasicFormList	property.loopVariableAggregation.definitions.description

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 aggregation variable or an expression that resolves to a variable name.

Data objects

Attribute	Type	Description
ID of the data object	Text	Provide a unique identifier for this entry.
Name	Text	Provide a human-readable name for this entry.
Type	Selection: String Long Boolean Date Enum	Select one of the supported types for this entry.
Default value	Text	Provide a value for this entry.

Exception Mappings

Attribute	Type	Description
Error code	Text	The error code where the exception should be mapped to.
Exception class	Text	The fully qualified java class name of the exception.
Root cause	Text	Optional setting. If set, both the exception class and the root cause need to match before the mapping is applied. This is useful to distinguish between similar exceptions, but with other origins.
Map child class	Boolean	If checked, an exception that is a child exception class (in the class hierarchy) will also match this line.

Execution listeners

Attribute	Type	Description
Event	Selection: Start End Take	The lifecycle event. The 'Take' event is only available for sequence flow.
Class	Text	Fully qualified classname of a class to be invoked when executing the task. The class must implement either JavaDelegate or ActivityBehavior.
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	Delegate Expression to be executed when the task is started. A delegate expression must resolve to a Java object, for instance a Spring bean. The object's class must implement either JavaDelegate or ActivityBehavior.
Fields	List

Fields

Attribute	Type	Description
Name	Text	The name of the element. This is the name displayed in the diagram.
String value	Text
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.
String	Text