Schleife abbrechen

Ereignisaktion - Kurzfassung

Zweck: Die Ereignisaktion beendet die Ausführung von Aktionen und die Iteration in einer übergeordneten Für jeden Eintrag wiederholen (Schleife) sofort, ohne die Ereignisverarbeitung insgesamt abzubrechen.

images/download/attachments/189440306/image-2024-11-27_7-29-38-version-1-modificationdate-1732889618112-api-v2.png

Die Schleife abbrechen-Ereignisaktion dient dazu die Iteration einer übergeordneten Für jeden Eintrag wiederholen (Schleife)-Ereignisaktion mit sofortiger Wirkung zu stoppen. Die Ereignisverarbeitung wird daraufhin nach bzw. "unterhalb" der Schleife fortgesetzt.

Typischerweise wird der Abbruch der Schleife an die Auswertung eines Abbruchkriteriums geknüpft, dessen Auswertung eine Fallunterscheidung im Aktionsblock der Schleife erfordert:

  • Im Allgemeinen wird die Wenn Dann Sonst-Ereignisaktion eingesetzt, um die bedingte Ausführung von Ereignisaktionen (abhängig von einer Regel-Konfiguration; s. Regeltypen) darzustellen.

  • Die Benutzer-Rückfrage-Ereignisaktion bedient den Sonderfall, dass die Entscheidung nicht per Regel ermittelt, sondern interaktiv vom Benutzer abgefragt werden soll.

  • Die Try-Catch-Aktion-Ereignisaktion kann verwendet werden, um eine Schleife als Reaktion auf einen Fehler zu beenden, ohne dass die Ereignisverarbeitung insgesamt stoppt.

HINWEIS◄ Die Variable $index dient zwar während der Ausführung einer Schleife als Schleifenzähler, steht aber nur innerhalb des Aktionsblocks zur Verfügung. Nach einem Abbruch einer Schleife durch die Schleife abbrechen-Ereignisaktion kann also nicht per direktem Lesezugriff auf die Variable $index festgestellt werden, in welcher Iteration der Abbruch ausgelöst wurde.

Konfiguration

Die Schleife abbrechen-Ereignisaktion verwendet keine Parameter.

Beispiele

Einfacher Anwendungsfall: Abbrechen einer Checkliste beim ersten nicht bestätigten Eintrag

Die Freigabe einer Tour soll nur dann ausgelöst werden, wenn der Benutzer sämtliche Schritte einer kleinen Checkliste bestätigt, die als Liste von Textwerten (String[]) in einer Variable checklist vorliegt.

  • Sobald der Benutzer einen Eintrag nicht bestätigt, soll die Abarbeitung der Checkliste abgebrochen werden.

  • Nach einem Abbruch soll eine Variable abortIndex auf die Listenposition verweisen, die nicht bestätigt wurde.

  • Nachfolgende Schritte sollen unabhängig von einem Abbruch der Checkliste ausgeführt werden, aber dabei die Werte der Variablen checklist und abortIndex auswerten.

Konfiguration:

Der Screenshot rechts zeigt die Für jeden Eintrag wiederholen (Schleife) für die Abarbeitung der Checkliste:

  • Im Parameter Wertauflöser für Einträge greift ein Variable-Wertauflöser auf die in der Variable checklist bereitgestellte String-Liste zu, über die iteriert werden soll.

  • Im Aktionsblock der Schleife wird eine Benutzer-Rückfrage-Ereignisaktion ausgeführt:

    • Als Text für die Rückfrage soll der für die Iteration relevante Textwert aus der checklist-Liste In Großbuchstaben ausgegeben werden.

    • Wird eine Rückfrage mit "Ja" bestätigt, soll sofort die nächste Frage erscheinen. Der Aktionsblock im Yes-Zweig (links) enthält deshalb keine Ereignisaktionen.

    • Lautet die Rückmeldung dagegen "Nein", soll die Abarbeitung der Checkliste abgebrochen werden. Der Aktionsblock im No-Zweig (in der Mitte) enthält zwei Ereignisaktionen:

      • Die Setze Wert-Ereignisaktion speichert den aktuellen Schleifenindex aus der vom System befüllten $index-Variable in der Variablen abortIndex , damit er für nachfolgende Abläufe "gemerkt" wird.

      • Die Schleife abbrechen-Ereignisaktion sorgt dafür, dass keine weiteren Rückfragen gestellt werden, aber die Ereignisbehandlung mit Aktionen unterhalb der Schleife (nicht im Bild) fortgesetzt wird.

    • Falls die maximale Wartezeit (s) abläuft, bevor eine Rückfrage beantwortet wird, soll die Ereignisverarbeitung insgesamt gestoppt werden, ohne dass eine Fehlermeldung erscheint. Dies gewährleistet die Abbrechen-Ereignisaktion im Timeout--Zweig (rechts).

images/download/attachments/189440306/image-2024-11-27_17-52-46-version-1-modificationdate-1732889618105-api-v2.png

Komplexerer Anwendungsfall: Abbrechen verschachtelter Schleifen über mehrere Stufen

Eine Ereignisbehandlung soll sämtliche Adressbucheinträge und Firmenadressen, für die Lesezugriff besteht, nach Adresskontakten mit Kontakttyp "Gebäude" (BUILDING) durchsuchen, um eine "Eindeutige Liste" (Set) mit Klartextbezeichnern je Gebäude zusammenzustellen, die in einem Hinweis angezeigt werden soll.

Die maximale Anzahl der ausgegebenen Zeilen soll durch einen positiven Integer-Wert in einer Variablen (limit) begrenzt werden.

In der folgende Konfiguration wird das Durchsuchen der Adresskontakte durch zwei verschachtelte Schleifen dargestellt, von denen die äußere über Adressen iteriert und die innere über die Adresskontakte innerhalb der jeweiligen Adresse.

Sobald die "Eindeutige Liste" (Set) die maximale Anzahl an Klartextbezeichnern erreicht hat, soll die Iteration über beide Schleifenebenen abgebrochen und die Liste der gesammelten Gebäudebezeichnungen in einem Hinweis erscheinen.

Laufzeitbeispiel:

Der folgende Screenshot zeigt eine Hinweis mit einer Liste von drei "Gebäudebezeichnungen", die offensichtlich zwei unterschiedliche Firmen betreffen:

images/download/attachments/189440306/image-2024-11-28_11-21-50-version-1-modificationdate-1732889618086-api-v2.png

ANMERKUNG◄ Die "Eindeutige Liste" (Set) wird hier nicht einfach als String ausgegeben, sondern per Text ersetzen noch kosmetisch überarbeitet, sonst wäre hier die übliche Listennotation ([ , , ]) zu sehen.

Konfiguration:

Der folgende Screenshot zeigt die Für jeden Eintrag wiederholen (Schleife)-Ereignisaktion für die äußere Schleife und (ganz unten) die nach Abschluss oder Abbruch der Iteration(en) auszuführende Hinweis anzeigen-Ereignisaktion für die Ausgabe.

  • Der Wertauflöser für Einträge für die äußere Schleife erstellt aus zwei Suchergebnissen (für Firmen und Adressen) über den Sammle Werte-Wertauflöser eine gemeinsame Liste von Adressen.

  • Die innere Schleife erhält als Bezugsobjekt je Iteration der äußeren Schleife eine konkrete Adresse, die entweder mit einer Firma oder einem Adressbucheintrag verknüpft ist.

    • Der Wertauflöser für Einträge der inneren Schleife verwendet einen Typisierte plurale Attribute (Wertauflöser), um alle Adresskontakt-Attribute mit dem benutzerdefinierten Subtyp "Gebäude" (BUILDING) innerhalb der Adresse aufzulisten.

      • Im Aktionsblock der inneren Schleife kombiniert ein Textverkettung-Wertauflöser Informationen aus der übergeordneten Adresse (address) und den Adressdaten im Adresskontakt (contactAddress) zu einer "Gebäudebezeichnung" für die Ausgabe.

      • Der verkettete Text wird über eine Liste modifizieren-Ereignisaktion an die über die Variable buildings bereitgestellte "Eindeutige Liste" (Set) übergeben.
        WICHTIG◄ Diese Variable muss vorab per Erzeuge Instanz-Wertauflöser mit dem Typ "Eindeutige Liste" (Set) initialisiert worden sein. Dieser Listentyp verhindert das Hinzufügen von Duplikaten ohne weiter Vorkehrungen.

      • Unabhängig davon, ob die aktuelle "Gebäudebezeichnung" tatsächlich hinzugefügt oder als Duplikat ignoriert wurde, prüft die anschließende Wenn Dann Sonst das vorgegebene Abbruchkriterium: Eine Objekt-Feld-Regel stellt per Vergleiche mit (Formulardesigner)-Vergleichstyp fest, ob das vorgegebene limit mit der aktuellen Länge (length) der buildings-Liste übereinstimmt.

        • Ist das limit erreicht, wird eine Schleife abbrechen-Ereignisaktion ausgelöst, die die innere Schleife beendet.

    • Unterhalb der inneren Schleife folgt eine weitere Instanz der Wenn Dann Sonst-Ereignisaktion, die inhaltlich exakt mit der vorherigen übereinstimmt. Diese zweite Prüfung ist erforderlich, damit auch die äußere Schleife abgebrochen wird, wenn das limit erreicht ist.

      ANMERKUNG◄ Das Abbruchkriterium für die äußere Schleife prüft hier formal nicht, ob die innere Schleife abgebrochen wurde. Die Prüfung verwendet nur dasselbe Abbruchkriterium. Für die äußere Schleife ist dabei nicht unterscheidbar, ob die innere Schleife per Abbruch beendet wurde, oder weil die untersuchte Adresse keine weiteren Gebäude enthält. Die Aktion Schleife abbrechen wird hier in beiden Schleifenebenen auch gezielt unabhängig davon ausgeführt, ob ohne Abbruch eine weitere Iteration erfolgen würde. Dies ließe sich bei Bedarf über die Boolean-Variable $last zusätzlich prüfen (s. Für jeden Eintrag wiederholen (Schleife).

images/download/attachments/189440306/image-2024-11-28_10-45-34-version-1-modificationdate-1732889618089-api-v2.png images/download/attachments/189440306/image-2024-11-28_10-20-53-version-1-modificationdate-1732889618095-api-v2.png

Sonderfall: Abbrechen einer Schleife in einer aufrufenden Ereignisbehandlung

Um einen Standardprozess zum Abbrechen von Schleifen definieren zu können, wurde ein Eigenes Aktionsevent eingerichtet (hier: XF_TERMINATOR), das anstelle eines direkten Aufrufs der Schleife abbrechen-Ereignisaktion über die Eigenes Aktionsevent auslösen (Aktion)-Ereignisaktion ausgelöst werden kann.

Konkret soll beim Abbrechen einer Schleife immer dann eine Warnmeldung wie die folgende ausgegeben werden, wenn ohne den Abbruch mindestens eine weitere Iteration ausgeführt werden würde.

images/download/attachments/189440306/image-2024-11-28_15-47-36-version-1-modificationdate-1732889618058-api-v2.png

Konfigurationsbeispiel für den Aufruf:

Der Screenshot rechts zeigt schematisch eine Ereignisbehandlung mit einer Für jeden Eintrag wiederholen (Schleife)-Ereignisaktion, in der abhängig von einem Abbruchkriterium in einer Wenn Dann Sonst-Ereignisaktion das Eigene Aktionsevent XF_TERMINATOR für den Schleifenabbruch ausgelöst wird.

Alle anderen Ereignisaktionen sind hier in Ausführen mit-Ereignisaktionen zusammengefasst, deren Beschriftung den Stellenwert für den Ablauf charakterisiert:

  • Die "loop actions" im Aktionsblock der Schleifen werden bei jeder Iteration ausgeführt. Dies betrifft auch die Iteration, inn der Schleife abbrechen (indirekt) ausgelöst wird.

  • Die Wenn Dann Sonst-Ereignisaktion prüft ein hier nicht näher bezeichnetes Abbruchkriterium als Bedingung für das Auslösen des Eigenen Aktionsevents XF_TERMINATOR im "Dann"-Zweig der Fallunterscheidung. Die dadurch ausgelöste Ereignisbehandlung (s. unten), muss eine Schleife abbrechen-Ereignisaktion enthalten, damit die Iteration der Schleife tatsächlich abgebrochen wird.

    HINWEISEigenes Aktionsevent auslösen (Aktion) überträgt zwar alle Variablen aus dem Aufrufkontext in den Datenkontext für aufgerufene Ereignisbehandlungen, also auch die Schleifenvariablen (s. Für jeden Eintrag wiederholen (Schleife)), die deshalb in Zusammenhang mit Prozessen beim Schleifenabbruch ausgewertet werden können. Allerdings werden umgekehrt geänderte Variablenwerte nicht in den Aufrufkontext zugrückgeschrieben, sodass der $index dort effektiv nicht einfach manipuliert werden kann, indem der Variable in der aufgerufenen Ereignisbehandlung ein höherer Wert zugeordnet wird.

  • Die "... more loop actions" unterhalb werden ebenfalls je Iteration ausgeführt. Sie entfallen aber für die Iteration in der der Abbruch ausgelöst wird.

  • Die "... more actions" unterhalb werden nach dem Abschluss der Schleife (mit oder ohne Abbruch) in jedem Fall ausgeführt.

images/download/attachments/189440306/image-2024-11-28_16-9-9-version-1-modificationdate-1732889618052-api-v2.png

Konfiguration:

Der Screenshot rechts zeigt die Konfiguration für eine Ereignisbehandlung, die den Standardprozess für einen Schleifenabbruch abbilden soll:

  • Als Auslösendes Ereignis dient ein Eigenes Aktionsevent mit dem Namen XF_TERMINATOR.

  • Als Prüfende Regel wurde eine Statische Regel konfiguriert, sodass die folgenden Aktionen immer als Reaktion auf das Ereignis XF_TERMINATOR ausgeführt werden.

  • Es sind zwei Aktionen bei bestandender Regel konfiguriert:

    • Die Wenn Dann Sonst-Ereignisaktion prüft, ob die im Schleifenkontext automatisch befüllte Boolean-Variable $last den Wert true enthält. Dies ist nur der Fall, wenn es sich um die letzte Iteration der übergeordneten Schleife handelt.

      • Der "Dann"-Zweig der Fallunterscheidung enthält keine Ereignisaktionen, da buchstäblich nichts passieren soll, wenn der Abbruch in der letzten Iteration einer Schleife ausgelöst wird.

      • Der "Sonst"-Zweig der Fallunterscheidung enthält eine Hinweis anzeigen-Ereignisaktion, die eine Notification vom Typ "Warning" ausgibt, wenn es sich um einen "signifikanten" Abbruch einer Schleife (vor der letzten Iteration) handelt. Die Wert-Konfiguration für die Meldung wird unten detaillierter dargestellt.

    • Die eigentliche Schleife abbrechen-Ereignisaktion soll in allen Fällen ausgeführt werden. Sie ist ist deshalb außerhalb der Wenn Dann Sonst-Ereignisaktion zu finden.

HINWEIS◄ Da die Schleife abbrechen-Ereignisaktion hier nicht im Kontext einer Für jeden Eintrag wiederholen (Schleife) verwendet wird, hat es keinen Sinn unterhalb weitere Ereignisaktionen anzuordnen. Diese würden niemals ausgeführt, da die Kontrolle mit dem Abbruch an die übergeordnete Schleife zurückgegeben wird.

images/download/attachments/189440306/image-2024-11-28_15-4-53-version-1-modificationdate-1732889618067-api-v2.png

Die Meldung bei einem "echten" Abbruch wird wie rechts abgebildet über den Wert aus Sprachverwaltung-Wertauflöser definiert,, der hier ohne echten Zugriff auf die Sprachverwaltung verwendet wird (weder Bundle noch Resource sind benannt):

  • Der Standardwert definiert einen englischen Text mit Parametern, denen unterhalb ausgehend von automatisch bereitgestellten Schleifenvariablen (s. Für jeden Eintrag wiederholen (Schleife)) Integer-Werte zugeordnet werden:

    • Der erste Parameter ({0}) soll angeben, in welcher Iteration der Abbruch erfolgt ist. Zum Wert der Variablen $index wird hier über den Einfache Berechnung-Wertauflöser der Wert 1 addiert, um die Zählung zur humanverträglicheren Variante mit dem Startwert 1 zu verschieben.

    • Dem zweiten Parameter ({1}) wird die Variable $length zugeordnet, die die Gesamtanzahl der Iterationen angibt.

images/download/attachments/189440306/image-2024-11-28_15-6-28-version-1-modificationdate-1732889618064-api-v2.png