Figure: Example Sequential Multi Instance Activity in the Eclipse Modeler
Stardust supports multiple execution instances. These multiple instances can be performed in parallel or sequentially.
Suppose a company needs a review task for a document review that should be performed by a specific number of users. The review is only considered as completed once all users have completed their review task. Instead of running a loop to give the task from one user to the next user once resolved, a multiple instances activity can be used. This task enables you to run a subprocess for each separate review task in a set of data.
Other common use cases are for example:
Multi instances tasks enable you to run a subprocess or application for each element of a data set. When this subprocess or application activity is performed, it creates a set of instances, one for each element of the data set. You can configure the activity to process these instances in parallel or sequentially. The entire multi instance block is completed when all instances are completed or aborted.
Sequential multiple instance activities are required if an instance should consider the result of the preceding instance.
If a multi instance activity is defined as sequential, all resulting instances are executed sequentially until the last instance has been completed. A new instance is generated for each data in the order they are received with the data set list after the previous instance has been completed.
Three horizontal lines indicate that the multi-instance activity is sequential.
Figure: Example Sequential Multi Instance Activity in the Eclipse Modeler
Figure: Example Sequential Multi Instance Activity in the Business Process Modeler
Note
Please use the sequential processing type with care. In some cases it might lead to uncompleted processes.
In case an application exception occurs, the last activity instance is interrupted and sequential processing will resume after a recovery. If a system exception, or any other condition causing the transaction to roll back, occurs, all instances of the multiple instance activity will roll back.
Multiple instances defined as parallel are executed at the same time until all instances are completed.
Three vertical lines indicate that the multi-instance activity is parallel.
Figure: Example Parallel Multi Instance Activity in the Eclipse Modeler
Figure: Example Parallel Multi Instance Activity in the Business Process Modeler
In case an application exception is thrown during the execution of an instance, this particular instance is interrupted and the other instances will be processed and completed normally. A recovery will restart processing of the interrupted instances.
If a system exception, or any other condition causing the transaction to roll back, occurs during processing of one instance, the corresponding activity thread will roll back. However, the other instances belonging to this multiple instance activity will not be affected.
The extraction of single elements from in data lists and assembly of out data lists from the return values of the single instances is performed via an index-based algorithm. Hence, each instance has access via the multiple instance access points to only its own in and out data element but not to the entire list.
Input and Output parameters are provided to specify the data parameters defined for the application or process interface accordingly.
If a subset of the instances in a multiple instance activity is aborted, the same semantics as in single-instance activities is employed:
By default all instances are processed in one transaction. You can configure the number of instances to process in one transaction for sequential multiple instance activities by enabling limitation and setting a value for the maximum batch size. The transaction will be committed after processing of the specified number of instances. A new transaction or activity thread will be started for processing subsequent activity instances and the instance counter and transaction duration timer will be reset to 0.
You can specify application activities and subprocess activities using a process interface as multi-instance activities. The following activity types are not supported as multiple instance activities:
In case multiple instance execution is required for any of these activity types, you can re-factor these activities into a subprocess using a process interface with the required parameters.
Multiple instance processing, both parallel and sequential, is not supported for activities that are Relocation Source.
Multiple instance parallel processing is not compatible with subprocesses of Execution type Synchronous/Shared Data. The reason is that in or out data mappings are performed concurrently on the same set of data, thus some of the instances will lose their own input and instead process the input from a concurrent activity instance. However for sequential processing the Execution type Synchronous/Shared Data is supported as each subsequent data mapping is performed after the previous activity has terminated.
The following list data types are supported as input or return data of multiple instance activities:
| Type | Restrictions | Comments |
|---|---|---|
| Document Lists (including Process Attachments) | none | |
| Folder Lists | none | |
| XSD-List typed nodes of structured data | Note that currently it is not possible to access list values of imported structured data types in the Eclipse modeler. | internally as well as externally defined types |
| java.util.List types | none | typed lists (untyped lists would return plain objects without specified method access types) |
| Java arrays | supported as input type only | |
| Java-based Enumeration types | supported as input type only | supported via array <some enum>.getClass().getEnumConstants() |
The following processing mode types can be set for an activity:
In the Business Process Web modeler, the processing mode can be set in the property pane of the activity. A Processing property page is available, where the parameters can be selected.
Selecting a processing mode for Multiple instance parallel or Multiple instance sequential enables multiple instance processing for the activity and adds the appropriate symbol to the activity in the model diagram.
For details on settings for multiple instance activities in the Business Process Web modeler refer to section Setting Processing Type Properties of chapter Specifying Activity Properties in the Business Process Modeling Handbook.
Input and Output Parameters can be defined to specify the data parameter definitions used for multi-instance processing.
Data mapping access points for multiple instance activities follow the existing semantics for setting the same for application activities and process interface. In the Web modeler, they can be easily identified in the Input Access Point and Output Access Point drop-down lists to be access points for multiple instances activities as they have the term List appended.
In the Eclipse modeler, the processing mode is set via the Control Flow. To use the multiple instance processing mode, select Multi Instance as Loop type.
If Multi-Instance is selected as Loop type in the Control Flow of an activity, the following Input and Output Parameters can be defined to specify the data parameter definitions used for multiple instance processing:
For details on setting control flow for multiple instance activities in the Eclipse modeler refer to section Control Flow of chapter Specifying Activities.
Data mapping access points for multiple instance activities in the Eclipse modeler follow the existing semantics for setting the same for application activities and process interface.
The limit of the list size which can be used with the new feature without running into transactional errors or performance issues depends on the layout of the runtime environment. For the standard setup on a small machine (4 cores) list sizes up to 10000 entries have been tested before running into transactional problems.
In this example we create a process to review a list of data and edit it if required. The review and update is done for each data element separately.
First we create a model in the Business Process Modeler with the following data types and data:
Now we create a process that we want to use as subprocess. We set the subprocess type to Provide Process Interface and enter parameter definitions that can be used as access points for the data flow of the data list.
As in data parameters we define the primitive String data for retrieving the data element of the current index and the primitive Number data, which will be used to show the current index of the data element. Similarly, we define the primitive String data as out data parameter to provide changes in the data element.
Figure: Process Interface settings
Then we enter two activities, one to display the index of the data element and one to review and update the data element.
Figure: Subprocess Diagram
To create the subprocess activity, drag the created subprocess to the diagram canvas of the main process.
In the General Properties pane, we select Subprocess with Execution type Synchronous/Shared Data and processing type Multi instance Sequential.
Figure: Setting Subprocess properties
In the Processing Properties page of the subprocess activity, we select the processing type Multi-instance Sequential if not already set.
We define the input and output parameters to apply to the parameters specified for the process interface accordingly. The input parameter definition points to the list data elements that we want to use to create activity instances from. Whereas the output parameter points to the array element used to capture data from the current activity instance. The index parameter provides the index of the list data element, which is currently processed.
Figure: Setting the processing type and parameters
For the main process we need the below mentioned tasks in the following sequence:
Figure: Main process with multiple instance activity
We use the following data flow for our String list:
As access points to the subprocess activity we select the input and output parameters for the processing of the multiple instance and the data path of the data elements accordingly.
Figure: Setting the access points
To test our example, we start the main process, enter values in the data list and complete the activity.
Figure: Entering data in the data list
At first the count of the current index is displayed, which is 0 for the first entry. Complete the activity.
Figure: Current index
Now the subprocess activity displays the first data element of the list. Review and optionally edit the String and complete.
Figure: Enter data element
For each data element that we have entered, this process is repeated. Once the last data element is reviewed, the activity to display the result is invoked. We can see the complete data list with the edited Strings.
Figure: Edited Data List
In this example we create a process where a list of String data is converted to upper case letters via a Message Transformation application. The converting is done for each data element separately.
First we create a model in the Business Process Modeler with a structured data type and according data with a list of Strings.
Now we create a message transformation application. We enter parameter definitions that can be used as access points for the data flow of the data list.
As input parameters we define a primitive of type Text for retrieving the data element of the current index. Similarly, we define a primitive of type String as output parameter to provide the converted String.
Figure: Parameter settings for the Message Transformation
In the Configuration tab, we map the input parameter to the output parameter and use the String method toUpperCase() to convert the String to upper case letters.
Figure: Message Transformation Configuration
To create the process we:
Figure: Process diagram
In the Processing Properties page of the application activity, we select the processing type Multi-instance Sequential.
We set the parameters to apply to the parameters defined for the message transformation application accordingly. In this example, we leave the Index Parameter empty as we do not use it.
Figure: Setting the processing type and parameters
Now we create the data flow for our String list:
As access points to the application activity we select the input and output parameters for the processing of the multiple instance and the data path of the data elements accordingly.
Figure: Setting the access points
To test our example, we start the main process, enter values in the data list and complete the activity.
Figure: Entering data in the data list
For each data element that we have entered, the message transformation is converting the String to upper case letters. Once the last data element is converted, the activity to display the result is invoked. We can see the complete data list with the converted Strings.
Figure: Converted Data List