Using Multiple Instance Activities

Infinity supports multiple execution instances. These multiple instances can be performed in parallel or sequentially.

Common Use Cases

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:

How do Multiple Instances Activities work

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.

Using Sequential Multiple Instances

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.

Sequential Multi Instance Activity
Figure: Example Sequential Multi Instance Activity in the Eclipse Modeler

Sequential Multi Instance Activity
Figure: Example Sequential Multi Instance Activity in the Modeling perspective

Note
Please use the sequential processing type with care. In some cases it might lead to uncompleted processes.

Behavior in case of exceptions

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.

Using Parallel Multiple Instances

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.

Parallel Multi Instance Activity
Figure: Example Parallel Multi Instance Activity in the Eclipse Modeler

Parallel Multi Instance Activity
Figure: Example Parallel Multi Instance Activity in the Modeling perspective

Behavior in case of exceptions

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.

Passing Data

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.

Aborting Subsets of a Multiple Instance Activity

If a subset of the instances in a multiple instance activity is aborted, the same semantics as in single-instance activities is employed:

Limiting the Transaction Batch Size

By default, during sequential execution, all instances are processed in one transaction. For large numbers of instances, this can lead to processing times exceeding the transaction timeout and hence in rollbacks of the transaction. In order to prevent this from happening, you can set a maximum batch size. This is especially helpful if the number of instances can vary strongly and very large numbers of instances (thousands and more) are possible.

If you specify a batch size, the transaction will be committed after processing the specified number of instances. New transactions will be started for batch-wise processing of the remaining instances thus limiting the transaction duration and preventing rollbacks. Please note however, that in case of exceptions, individual batches could roll back individually. In this case, a recovery will be required to restart processing for the remaining instances. Hence, batch processing is not advisable in situations where all instances are absolutely required to be processed within a short timeframe or where temporary states of partial processing would lead to major issues.

Note that if the activity is an interactive activity, setting the batch size has no effect, since the inherent implementations of the interactive activities are causing a transaction commit after each activity create or suspend action, thus interactive multi-instance activities are always behaving as if the batch size is set to 1.

The three most common examples for batch size settings are the following:

  1. No batch size: process all in one transaction
  2. Batch size of x: for very large lists to avoid transaction timeouts
  3. Batch size of 1: to commit every iteration, e.g. for subprocesses to only roll back the last subprocess in case of an error and not affect the previous iterations

Modeling Multiple Instance Activities in Infinity

Supported Activity Types

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.

Sub-process invocation via Multiple Instance activities

The copy all data is supported for multiple instance activities, as well. For more information, please refer the chapter Data Copy and Mapping Semantics.

Restrictions on Relocation Sources

Multiple instance processing, both parallel and sequential, is not supported for activities that are Relocation Source.

Restrictions on Subprocesses with Synchronous/Shared Data

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.

Supported Parameter Data Types

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()

Processing Modes

The following processing mode types can be set for an activity:

Using Multiple Instances in the Eclipse Modeler

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.

Setting input and output parameters in the Eclipse Modeler

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.

Setting data mappings and access points in the Eclipse modeler

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.

Using Multiple Instances in the Modeling Perspective

In the Modeling perspective, 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 Modeling perspective refer to section Setting Processing Type Properties of chapter Specifying Activity Properties in the Business Process Modeling Handbook.

Setting input and output parameters in the Modeling perspective

Input and Output Parameters can be defined to specify the data parameter definitions used for multi-instance processing.

Setting data mappings and access points in the Modeling perspective

Data mapping access points for multiple instance activities follow the existing semantics for setting the same for application activities and process interface. In the Modeling perspective, 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.

Using Multiple Instances in the Model & Go! Perspective

In the Model & Go! perspective, Activity Groups can be configured to spawn a Sub-Process Instance for each unique instance of the Primary Business Object's referenced Business Object.

For details please refer to the chapter Working in the Process Definition View of the Model & Go! Handbook.

Limitation of List Size

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.

Use Case Examples

Multiple Instance Subprocess Activity Example

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 Modeling perspective with the following data types and data:

Creating the Subprocess

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.

Process Interface Settings
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.

Subprocess
Figure: Subprocess Diagram

Creating the Subprocess activity

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.

Setting Subprocess properties
Figure: Setting Subprocess properties

Setting the Processing 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.

Setting the processing type and parameters
Figure: Setting the processing type and parameters

Creating the main process

For the main process we need the below mentioned tasks in the following sequence:

  1. a Start event
  2. a manual task for entering the data list
  3. the subprocess activity, which will be defined as multiple instance task
  4. a manual task to display the updated list

Main process with multiple instance activity
Figure: Main process with multiple instance activity

Setting the Data Flow

We use the following data flow for our String list:

  1. a default in and out data mapping to the first activity to retrieve the data list
  2. an in and out data mapping to the subprocess activity
  3. an out data mapping to the last activity to display the results in the data 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.

Setting the access points
Figure: Setting the access points

Running the Example

To test our example, we start the main process, enter values in the data list and complete the activity.

Entering data in the data list
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.

Current index
Figure: Current index

Now the subprocess activity displays the first data element of the list. Review and optionally edit the String and complete.

Edit data element
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.

Edited Data List
Figure: Edited Data List

Multiple Instance Application Activity Example

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 Modeling perspective with a structured data type and according data with a list of Strings.

Creating the Message Transformation application

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.

Parameter settings for the Message Transformation
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.

Message Transformation Configuration
Figure: Message Transformation Configuration

Creating the Process

To create the process we:

  1. Create a Start event
  2. Create an activity for entering the data list
  3. Drag the message transformation application to the canvas to create the application activity
  4. Create an activity to display a list with the converted String data

Process diagram
Figure: Process diagram

Setting the Processing Properties

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.

Setting the processing type and parameters
Figure: Setting the processing type and parameters

Setting the Data Flow

Now we create the data flow for our String list:

  1. a default in and out data mapping to the first activity to retrieve the data list
  2. an in and out data mapping to the application activity
  3. an out data mapping to the last activity to display the results in the data 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.

Setting the access points
Figure: Setting the access points

Running the Example

To test our example, we start the main process, enter values in the data list and complete the activity.

Entering data in the data list
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.

Converted Data List
Figure: Converted Data List

Multiple Instance Model & Go! Example

Assume we have three Business Objects of the following structure:

VENDOR data
Figure: Structured data type for VENDOR data

PRODUCT data
Figure: Structured data type for PRODUCT data

DISTRIBUTOR data
Figure: Structured data type for DISTRIBUTOR data

Consider the following relationships of the VENDOR Business Object:

Relationships of VENDOR data
Figure: Relationships of VENDOR data

Activity Groups can be set up to spawn sub-process instances from either Products of Vendor or Distributors of Vendor.

Suppose the instances of VENDOR are the following:

VendorId ProductIds DistributorIds
ACME 1,2,3 A,B,C
USA VENDING 4,5,6 E,F,G
MEGA CORP 7,8,9 H,I,J

For a Process Instance with VendorId = ACME, sub-process instances would be spawned as shown in the graphic below:

Spawned Sub-Process Instances
Figure: Spawned Sub-Process Instances