Event action – Abstract
Purpose: This event action immediately ends the execution of actions and the iteration in a parent For each loop without aborting the entire event processing.
Tooltip
Usage: The event action is only useful within a For each loop. As a rule, Break loop is used in the action block of the relevant loop. However, the aborted loop can also be located in a called event handling. The use of Break loop only makes sense in the context of an event action with a case distinction (e.g. If then else, User callback, Try/Catch actor), unless the parent loop should be terminated for test purposes.
Note: The event action does not provide any information on the loop termination (no flag, no index value) for any subsequent event processing. Corresponding assignments must be configured explicitly if required.
The Break loop event action is used to stop the iteration of a parent For each loop event action with immediate effect. Event processing is then continued after or 'below' the loop.
If multiple instances of the For each loop event action are used in a nested manner, the Break loop event action only ends the iteration at the level at which it is executed. Parent level loops are not cancelled.
In special cases, the For each loop event action to be cancelled is located in a calling event handling that directly or indirectly triggers the event handling with the Break loop event action in the context of the loop.
Typically, the cancellation of the loop is linked to the evaluation of a cancellation criterion, the evaluation of which requires a case distinction in the action block of the loop:
Generally, the If then else event action is used to represent the conditional execution of Event actions (depending on a rule configuration; see Rule types).
The User callback event action handles the special case where the decision is queried interactively by the user rather than being determined by rule.
The Try/Catch actor event action can be used to end a loop in response to an error without halting event processing altogether.
►NOTE◄ Although the $index variable serves as a loop counter during the execution of a loop, it is only available within the action block. This means that it is not possible to determine in which iteration the cancellation was triggered by direct read access to the $index variable after a loop has been cancelled by the Break loop event action.
Configuration
The Break loop event action does not use any parameters.
Examples
Simple use case: Cancelling a checklist at the first unconfirmed input
The release of a tour should only be triggered if the user confirms all steps of a small checklist, which is available as a list of text values (String[]) in a checklist variable.
As soon as an input is not confirmed by the user, the processing of the checklist should be cancelled.
After an abort, the abortIndex variable refers to the list item that has not been confirmed.
The following steps should be carried out independently of cancelling the checklist, but should evaluate the values of the checklist and abortIndex variables.
Configuration:
|
The screenshot on the right shows the For each loop used to process the checklist:
In the Resolver for entities parameter, a Variable resolver accesses the String list provided in the checklist variable, which is iterated over.
A User callback event action is executed in the action block of the loop:
The relevant text value for the iteration from the checklist list should be output in Upper case as the Text for the query.
If a query is confirmed with ‘Yes’, the next question should appear immediately. The action block in the Yes branch (left) therefore does not contain any event actions.
If the response is ‘No’, the processing of the checklist should be aborted. The action block in the No branch (in the centre) contains two event actions:
The Set value event action saves the current loop index from the $index variable filled by the system in the abortIndex variable so that it is ‘remembered’ for subsequent processes.
The Break loop event action ensures that no further queries are made, but that the event handling is continued with actions below the loop (not in the image).
If the Max. wait time (s) expires before a query is answered, event processing should be stopped altogether without an error message appearing. This ensures the Abort event action is in the Timeout branch (right).
|
|
More complex use case: Aborting nested loops over several stages
An event handling searches all address book entries and company addresses for which read access exists for address contacts with the Contact type ‘Building’ (BUILDING) in order to compile a ‘Unique list’ (Set) with plain text identifiers for each building, which is displayed in a note.
The maximum number of rows output should be limited by a positive Integer value in a variable (limit).
In the following configuration, searching through the address contacts is displayed by two nested loops, of which the outer one iterates over addresses and the inner one over the address contacts within the respective address.
As soon as the ‘Unique list’ (Set) has reached the maximum number of plain text identifiers, the iteration over both loop levels is cancelled and the list of collected building names appears in a notification.
Runtime example:
The following screenshot shows a notification with a list of three ‘building names/numbers’, which obviously refer to two different companies:
►NOTE◄ The ‘Unique list‘ (Set) is not simply output here as a string, but is cosmetically revised using Replace text, otherwise the usual list notation ([ , , ]) would be visible here.
Configuration:
The following screenshot shows the For each loop event action for the outer loop and (at the bottom) the Show alert event action for the output to be executed after completion or cancellation of the iteration(s).
The Resolver for entities for the outer loop creates a common list of addresses from two search results (for Company accounts and Addresses) via the Collect values resolver
The inner loop receives a specific address as a reference object for each iteration of the outer loop, which is linked to either a company or an address book entry.
The Resolver for entities of the inner loop uses a Plural typed attribute resolver to list all address contact attributes with the user-defined Subtype 'building' (BUILDING) within the address
In the action block of the inner loop, a Concat strings resolver combines information from the parent address (address) and the address data in the address contact (contactAddress) to create a 'building name' for the output.
The concatenated text is transferred via a Modify list event action to the 'Unique list' (Set) provided via the buildings variable.
►IMPORTANT◄ This variable must have been initialized in advance using the Create instance resolver with the 'Unique list' (Set) type. This list type prevents the addition of duplicates without further precautions.
Regardless of whether the current 'building name' was actually added or ignored as a duplicate, the subsequent If then else checks the specified cancellation criterion: An Entity property rule uses the Compare with (Form designer) compare type to determine whether the specified limit matches the current length (length) of the buildings list.
Below the inner loop is another instance of the If then else event action, which is exactly the same as the previous one in terms of content. This second check is necessary so that the outer loop is also aborted when the limit is reached.
►NOTE◄ The cancellation criterion for the outer loop does not formally check here whether the inner loop has been cancelled. The check only uses the same cancellation criterion. For the outer loop, it is not possible to distinguish whether the inner loop was aborted or because the address under investigation contains no further buildings. The Break loop action is also executed in both loop levels regardless of whether a further iteration would take place without cancellation. If required, this can also be checked using the Boolean variable $last (see For each loop.
|
|
Special case: Cancelling a loop in a calling event handler
In order to be able to define a default process for aborting loops, a Custom action event has been set up (here: XF_TERMINATOR), which can be triggered via the Dispatch action event event action instead of a direct call of the Break loop event action.
Specifically, when a loop is broken, a warning message such as the following should always be displayed if at least one further iteration would be executed without the cancellation.
Configuration example for the call:
|
The screenshot on the right schematically shows an event handling with a For each loop event action, in which the custom action event XF_TERMINATOR is triggered for the loop cancellation depending on a cancellation criterion in an If then else event action.
All other event actions are summarised here in Execute with event actions, whose labelling characterises their significance for the sequence:
The ‘loop actions’ in the action block of the loops are executed for each iteration. This also applies to the iteration in which the Break loop is (indirectly) triggered.
The If then else event action checks an unspecified cancellation criterion as a condition for triggering the custom action event XF_TERMINATOR in the ‘Then’ branch of the case differentiation. The event handling triggered by this (see below) must contain a Break loop event action so that the iteration of the loop is actually cancelled.
►NOTE◄ The Dispatch action event transfers all variables from the call context to the data context for event handling calls, including the loop variables (see For each loop), which can therefore be evaluated in connection with processes when the loop is broken. On the other hand, changed variable values are not written back to the call context, so that the $index cannot effectively be manipulated there simply by assigning a higher value to the variable in the called event handling.
The ‘... more loop actions’ below are also executed for each iteration. However, they are omitted for the iteration in which the cancellation is triggered.
The ‘... more actions’ below are always executed after the loop is completed (with or without cancellation).
|
|
Configuration:
|
The screenshot on the right shows the configuration for an event handling that maps the default process for a loop cancellation:
A Custom action event with the name XF_TERMINATOR is used as the Triggering event.
A Static rule has been configured as the Validating rule so that the following actions are always executed in response to the XF_TERMINATOR event.
There are two Actions on passed rule configured:
The If then else event action checks whether the Boolean variable $last automatically filled in the loop context contains the value true. This is only the case if it is the last iteration of the parent loop.
The ‘Then’ branch of the case differentiation does not contain any event actions, as nothing should actually happen if the cancellation is triggered in the last iteration of a loop.
The 'Else' branch of the case differentiation contains a Show alert event action that issues a notification of the 'Warning' Type if there is a 'significant' break in a loop (before the last iteration). The value configuration for the Message is shown in more detail below.
The actual Break loop event action should be executed in all cases. It can therefore be found outside the If then else event action.
►NOTE◄ There is no point in arranging further event actions below because the Break loop event action is not used here in the context of a For each loop. These would never be executed, as the control is returned to the parent loop with the cancellation.
|
|
|
The Message for a 'real' cancellation is defined as shown on the right via the Value from localization resolver, which is used here without real access to the Localization (neither Bundle nor Resource are named):
|
|