For each loop
See also: Break loop
Event action – Abstract
Purpose: Repeats a block of event actions for a list of objects or a specified number of repetitions.
The For each loop event action repeats a block of event actions either for a list of entries or for a number of repetitions defined by a numerical value.
The following variables are available for the event actions within the loop, to which the system automatically assigns values at the beginning of each iteration:
|
Variable name |
Type |
Automatic value assignment at the beginning of an iteration |
|
$index |
Integer |
The current iteration index starting at 0 |
|
$length |
Integer |
The number of planned repetitions (depending on the value Resolver for entities parameter). |
|
$first |
Boolean |
true in the first iteration ($index=0), otherwise false |
|
$last |
Boolean |
true in the last scheduled iteration, otherwise false |
►NOTE◄
Within the loop, these variables can be assigned different values by event actions (e.g. Set value or Store value as variable).
At the end of an iteration, the current value for the iteration index ($index) is compared with the value valid at the beginning of the iteration. If the current value is lower than the previous one, the variable will be assigned the previous higher value. So the iteration index can only be 'moved' forward and not backward, which could cause an endless loop.
Value assignments to the $length variable during an iteration are basically 'lost' at the end of the iteration. If a loop is executed over a list of entries, the value for $length is determined only once (before the start of the first iteration). Manipulating the list by removing or adding entries during iterations is possible in principle, but does not change the value of $length (see below: Clone list for manipulation parameter).
As long as the current (possibly manipulated) iteration index satisfies the condition $index < ($length - 1) at completion, the loop continues with a new iteration with an iteration index increased by 1.
A loop can therefore be aborted after the current iteration is completed, by assigning as an iteration index a value that does not satisfy the condition $index < ($length - 1). From a pragmatic point of view, the value $length is often used for this purpose.
The Break loop event action can be used to abort a loop immediately (without completing the current iteration).
The variables managed by the system apply exclusively within the loop. So, for example, an event handler that follows a For each loop cannot access the number of repetitions executed via the $length variable. In order for corresponding information to be available after the loop is completed, the corresponding value must be explicitly assigned to a variable by an event action within the loop, which the system does not assign automatically.
Configuration
The optional Save Object in variable parameter can be used to define the name of a variable that provides access to the outer reference object in the context of which the For each loop event action is executed as a whole within the loop.
The corresponding value assignment applies only within the loop. Any existing association for the same variable outside of the loop is only temporarily overlaid by this.
The parameter is only relevant if the loop is to iterate over a list of entries, since then within the loop a different entry is considered as the reference object in each iteration.
If, on the other hand, only a specified number of repetitions is to be executed (see Resolver for entities parameter), then the outer reference object also applies within the loop as the reference object.
The optional Resolver for entities parameter defines the iteration scheme for the loop. The following cases are to be distinguished:
The parameter defines a resolver that returns a numerical value (>0) at runtime. Then this value – if necessary after rounding down to an integer – determines the number of iterations of the loop to be executed. In all iterations, the outer reference object is considered the reference object.
The parameter defines a resolver that returns a list of entries at runtime. Then the loop iterates over these entries. Within the loop, a different entry is considered the reference object in each iteration.
The parameter does not define a resolver ('no value'). Then the outer reference object is passed to the loop. If this is a list of entries, the loop iterates over these entries.
►NOTE◄ In case 3, if the outer reference object is not a list, the loop is not executed. The attempt to pass a single numerical value (in the sense of case 1) as an outer reference object to a loop fails with an error message.
The Clone list for manipulation option should be used if the closure refers to a list of entries (case 2 or 3) that is to be manipulated in the course of the iterations by removing or adding entries:
If the option is set, then a 'clone' of the list is created before the start of the loop, which is then iterated over. Manipulations of the list by adding or removing entries (see Modify list or List item) then have no influence on the iteration scheme.
If the option is not set, then list manipulations are also possible. However, they can lead to unexpected results or errors when processing the loop, because the iteration scheme can be affected by changes to the list. Adding or removing entries moves existing entries and changes the 'length' of the list if necessary, while neither the iteration index ($index) nor the number of scheduled repetitions ($length) automatically respond to such changes. For example, if more entries are removed from a list than are added, the iteration scheme will eventually become stalled when the next entry is to be assigned for a new iteration, causing an error. This can be prevented by adjusting the iteration index (e.g. assigning $index=$length via Set value) to end the loop early. However, it is not possible to increase the number of iterations to be executed by accessing $length if more entries should be added than removed within the loop.
Below the parameters, the event actions to be executed in the loop can be added via the 
symbol.
Examples
Loop over a given number of repetitions
Within a loop, a Custom action event 'Allocate container' is triggered for a given shipment so often that the number of containers allocated as a result matches the number of Euro pallets determined for the shipment.
|
The For each loop event action is parameterized within an event handling for the 'Shipment' business object as shown on the right:
|
|
Loop over a list of entries
When a specific working state is assigned to a shipment, an event handler should display the names of all indicator attributes set for that shipment in one notification.
|
Within an event handling triggered by the working state in question, a For each loop event action is configured as shown on the right:
The reference object within the loop is therefore a Flag type in each case. |
|
|
Inside the loop we configure a Show alert (Popup) event action as shown on the right:
►NOTE◄ Instead of or in connection with the internal ID of the shipment, for example, the value of a reference attribute with an order number or another characteristic that sufficiently identifies the shipment could also be issued. |
|
Runtime example:
Loop with 'Abort criterion'
A shipment data input form shall offer users the possibility to enter the weight of a number of packages for the same shipment item in a small popup dialog. In the end, only the aggregated total weight is to be stored in the shipment item.
|
When the 'Weight entry' is opened for an item, the dialog shown on the right is to be called cyclically to query weights of individual packages until the user acknowledges the dialog with the default value of '0', i.e. without entering a weight, via the OK button. As shown in the image on the right, the total weight entered so far should be displayed in the title bar, while a list of the entries made so far for each package should appear line by line in the dialog itself for checking purposes. ►NOTE◄ It is assumed that the user only enters whole numbers for the weight. No special precautions are taken with regard to the input format for this example. |
|
Configuration:
|
An event handling is initiated via a Custom action event, which can be triggered when clicking on a Button in the item level of the input form. This event handling contains the configuration shown on the right for a For each loop:
|
|
|
|
|
|
