Iterations and Loops Concepts
Iteration and Looping Implementation in Flows for APEX
Flows for APEX Enterprise Edition v24.1 introduces BPMN Iterations and Loops. This section describes some of the major implementation concepts.
Iterated and Looped Activities
Iterations and Loops can be specified on Tasks (all task types) and collapsed Sub Processes.
Call Activities are currently not able to be looped or iterated. Any iterated or looped sub process cannot contain a nested call activity.
Iteration Subflows
When the Flows for APEX engine processes an object (a task or sub process activity) that contains a loop or iteration marking, it creates a separate subflow for the iteration to occur in. The parent activity, which is on the original subflow, is put into a status of iterating and is then inactive until the iteration or loop is complete.
Parallel Iterations. For parallel iterations, an iteration subflow is created for each item in the input collection. So a parallel iteration behaves like an implicit parallel gateway, with one forward path for each input. Each iteration path is numbered with a loop_counter, numbered 1 - n for the n input items in the input collection.
Each iteration path ends at an implicit merging parallel gateway until all other iteration paths are completed, or the completion condition is satisfied. While waiting for other iterations to complete, subflows are put into status waiting iterations.
Each parallel iteration path is created with its own process variable scope.
Sequential Iterations. For sequential iterations, a single iteration subflow is created, and each iteration of the activity is completed in sequence until the iteration is complete or the completion condition is satisfied.
All sequential iterations operate in the scope of the parent object.
Loops. For loops, a single iteration subflow is created, and each loop of the activity is completed in sequence until the completion condition is satisfied. If the loop exceeds 1000 cycles, the loop terminates to prevent accidental infinite looping.
All loop iterations operate in the scope of the parent object.
Input Collection
The input collection specifies the data that will be used for each iteration. An input collection is required for a parallel or sequential iteration, but not for a loop. When the iterations are created, each value in the input collection will be created as a process variable in the appropriate scope ready for the iteratin to be processed.
The input collection can be specified as one of three types.
- Process Variable containing a List. Specify the name of a process variable containing a colon (:) separated list in a varchar2 process variable. For a list you also need to specify the Input Element - this is the name of the process variable that will be created in each iteration to contain items from the list.
- Process Variable containing an Array. Specify the name of a json-typed process variable containing a json array. Each row of the array will create an iteration, with a process variable for each of the elements inside the array row. The process variables created will use the key as the name of the variable, and will have a value of the same type as the json element.
- SQL Query. Specify a SQL Query to be used as the iteration input. Each row returned will create one iteration. Process variables will be created for each of the columns returned, named with the column name or column alias.
Description
It can be hard to keep track of what each iteration represents when administering or problem solving iterations - so you can create a description for each iteration. The iteration description is used within the Flows for APEX Flow Viewer, and is also added to the Output Collection. the Iteration Description is specified as a literal string that can contain text and substitution values from the input collection and pseudo-columns like LOOP_COUNTER.
For example:
Iteration &LOOP_COUNTER. Employee &ENAME. (ID-&EMPNO.)
creates an Iteration Description (for example)
Iteration 3 Employee SCOTT (ID-7788)
Output Collection
A loop or iteration creates an Output Collection, which is a JSON-typed process variable containing an array containing output details for the iteration. You specify the collection type (currently always a process variable containing a JSON array) and the process variable name in the model. In addition, you can add a colon (:) separated list of process variables that are present inside each iteration that you want to include in the output collection when the iteration is completed.
The output collection must be specified for parallel and sequential iterations and for loops.
Completion Condition
The completion condition allows you to specify when a loop or iteration is complete, You must have a completion condition for a loop, but you can also have a completion condition on an iteration.
The completion condition is evaluated at the end of an iteration or loop, and determines:
- for a loop, whether another loop is started or the loop completes.
- for a parallel or sequential iteration, if the iteration is completed. If so, any uncompleted iteration subflows are terminated, and the process moves onto the next step.
The completion condition can be a PL/SQL expression or function body returning a boolean result. If true the loop or iteration is complete.
Flows for APEX makes the following pseudo-variables available to the evaluation of completion condition.
| variable | description |
|---|---|
| loop_counter | the loop counter value for the current iteration on loop cycle |
| total_instances | total number of iterations / loops |
| active_instances | number currently active iterations / loops |
| completed_instances | number of completed iterations / loops |
| terminated_instances | number of terminated iterations / loops |
Nesting Loops and Iterations
Loops and iterations can be nested inside other iterated or looped sub processes, to any reasonable level of nesting.
Note that deeply nested iterations and loops will create many copies of tasks and sub-processes, and it can be difficult for a business user or administrator to understand where problems lie when deeply nested processes run into errors!
The Flows for APEX Application and the Flow Viewer plugin, which can be built into your application, have been enhanced so that it is easier to track, manage, and understand complex iterated workflows, via a number of features which areexplained below.
- Iteration Path
- Iteration aware BPMN Viewer Plugin (also part of the Flows for APEX application).
Iteration Path
The Flows for APEX engine keeps track of iterations / loops, loop counts and nested iterations. As in the diagrams above, tasks are displayed with the loop counter in square brackets after the task name. Tip: If you are using Iterations, you will find it much easier to see what is going on from the Flow Viewer in the Flows for APEX application if ‘Iteration Path’ is displayed in the Subflow tab. If it is not visible, use the APEX Interactive Report controls to make it a displayed column, and then save the report as the default report.
Iteration Aware Viewer
This allows you to drill into nested iterations and loops to see the current status of iterated and looped business processes.
Example Nested Iterated Process
Our example is a contrived example working on EMP and DEPT to create a process where HR and managers perform an annual review of government employment eligibility (visa statrus) and then reviews each employee’s salary and position. At the first level, we start a parallel iteration for each department in the DEPT table. Then, inside the ‘Department Review’ sub process, we start a second iteration in parallel for each employee in the department, based on a query from EMP. While this is a contrived example, it shows how an iteration is defined, how iterations can be nested, and shows how the BPMN Viewer can be used to drill down iinto iterated sub processes, selecting the required iteration each time you need to drill down.
The first animated diagram shows the process diagram in the BPMN Modeler, showing how the iterations are defined.
The animation loops for a while. To loop further, reload the page.
Run Time Viewer Iteration Support
This next animated image shows a user test-running the model inside the Flows for APEX Application Flow Monitor. You can see how we start the process, step it forward, and how to drill into a particular iteration path in the viewer to show progress or problems in each iteration path.
