Repeating activities in a process by using multi-instance loops

A multi-instance loop defines process activity repetition. It allows an activity to be executed for each item in a data array. The multi-instance loop is available with Call Activity, User Task, Sub-Process, and Service Task activities.

To use a multi-instance loop, you need a list of objects to iterate, an object to process each element from the list, and optionally, a loop completion criteria. The multi-instance loop iterates through the list of objects by using the iterator and performs the actions within the loop by using the values from the iterator object. For each iteration, a multi-instance loop also verifies the loop completion criteria, if specified.

The multi-instance loop stops responding when any of the following conditions are met:

All objects in a list are processed.
Loop completion criteria are evaluated to be true.

Sequential multi-instance loops

The sequential multi-instance loop iterates the Loop Input Data one by one. If there is any wait state in the loop actions, the next iteration is started only when the wait state of the current iteration is complete.

Parallel multi-instance loops

The parallel loop executes each iteration one by one until an action hits the wait state. When any action within the loop hits the wait state, the parallel loop continues iterating the remaining elements from the Loop Data Input. Except for when there is any wait state in the loop, there is no difference between the Sequential and Parallel loops.

To enable a multi-instance loop

Log in to BMC Helix Innovation Studio and navigate to the Workspace tab.
Select the application or library in which your process exists.
In the application, click the Processes tab.
Click the process name where you want to add the multi-instance loop.

In the Process designer, select the activity element for which you want to use a multi-instance loop.

In the Properties pane, in the MULTI INSTANCE LOOP section, enter the values for the following properties:

Property	Description
Loop Type	Category of loop either sequential or parallel. Important: If you do not select the Loop Type, the multi-instance loop is not enabled for the activity. Best practice: We recommend that you use a sequential multi-instance loop.
Loop Data Input	An expression that represents a collection of items. It refers to an array of data such as a list of task records, or a list of approvers.
Input Data Item	A process variable that represents the data type of each item. It is assigned a value from the Loop Data Input array, such as a task record or the name of an approver. You can also provide a list as an input variable for this element. For more information about lists, see Creating-lists-from-processes.
Completion Criteria	Option to process the loop only for specific data. A multi-instance activity ends when all instances are completed. However, you can specify an expression that is evaluated every time an instance ends. When this expression resolves to true, the multi-instance activity ends, and the process continues. For example, in an approval use case, you can use the completion condition to define that at least 3 out of 5 approvers approve the request. After 3 out of 5 approvers approve the requests, the multi-instance loop is marked as complete.

Click Save.

Example 1: Using a multi-instance loop on a sub-process

The following images illustrate a process where the process fetches a list of records. For each record, it updates the record integer field and appends the record display ID to a process variable ID. The updating of records and appending ID steps are performed in the sub-process.

In this example, the Multi-instance loop is defined on the Sub-Process.

22_1_multi instance loop on sub process.png

The following table shows the sample configuration of the process variable and the process steps (Get Loop Source Records, Sub Process, Increment Integer Field, and Append Display ID) for the above process:

Process steps	Sample configuration
Configure the process variable
Get Loop Source Records
Update the Loop Data Input field. Important: The value Output is the output value from the Get Loop Source Records activity.
Increment Integer Field
Append Display ID

Example 2: Using Get Records By Query to get the list of objects

An Order Management application is where a user adds multiple items in a shopping cart and places an order. After the user submits the order, the Place Order process iterates through all items in the cart, uses the cost of each item to calculate the total cost, and creates an order record with the total cost. The second process Cart Cleanup, clears the cart after the order is placed.

The following image provides an overview of the Place Order process:

22_1_multi-instance loop Get Records By Query.png

The following table shows the sample configuration of the process variable and the process steps:

Process steps	Sample configuration
Use the following process variables: CartRecord of type Record to process each record from the Cart totalCost of type Integer to hold the total cost of Order
Run the Get Records By Query action to get all the matching records.
Run Compute Value Action to compute the totalCost of the order. totalCost is a process variable of type Integer to hold the total cost of the order.
Add computing value for multi-instance loop.

Similarly, after the order is placed, we need to clear the cart. The Cart Cleanup process needs one local variable CartRecord of the type Record. First, the process fetches all the records from the current cart by using Get Records by Query and then applies the multi-instance loop on the Delete Record action.

The following image provides an overview of the Cart Cleanup process: