Marker für Mehrfachinstanzen

Überblick

Verwenden Sie Marker, um eine Aufgabe zu konfigurieren, die einmal für jedes Element in einer Listen-Variable ausgeführt wird, wodurch mehrere sequenzielle oder parallele Ausführungen erstellt werden. Besuchen Sie Marker im Kapitel BPMN-Primer für Notation und konzeptionelle Anleitung.

Wann Mehrfachinstanzenmarker verwendet werden sollten

Verwenden Sie einen Marker für mehrere Instanzen, wenn Sie eine Liste von Elementen haben und dieselbe Aufgabe für jedes Element einmal ausführen müssen – zum Beispiel:

• Validieren jeder Rechnung in einer Liste von Rechnungs-IDs
• Anreicherung einer Reihe von Datensätzen durch Aufruf einer externen API pro Datensatz
• Versenden einer Benachrichtigung an jeden Empfänger in einer Liste

Ohne einen Marker müssten Sie eine manuelle Schleife mit Sequence-Flows erstellen, was schwieriger zu lesen und schwieriger zu verfolgen wäre. Ein Marker für mehrere Instanzen hält Ihr Prozessdiagramm übersichtlich und bietet Ihnen im Ausführungspfad eine detaillierte Darstellung für jedes Element – der Durchlauf jedes Elements erscheint separat, mit eigenem Status und eigener Ausgabe.

Verwenden Sie den Modus Sequenziell, wenn die Reihenfolge entscheidend ist oder jeder Durchlauf vom vorherigen abhängt. Verwenden Sie den Modus Parallel, wenn die Elemente unabhängig voneinander sind und Sie einen schnelleren Durchsatz wünschen.

Unterstützte Sammlungstypen

Maestro behandelt die folgenden Sammlungstypen als schleifenfähig für die Ausführung von Mehrfachinstanzen:Wenn Ihre Variable einer dieser Typen ist, können Sie sie direkt im Feld „Items“ verwenden:

• System.Collections.Generic.List<T>
• System.Collections.Generic.IList<T>
• System.Collections.Generic.IEnumerable<T>
• System.Collections.IEnumerable
• System.Data.DataTable
• Newtonsoft.Json.Linq.JArray
• Typen, bei denen die Typen collectionDataType mit beginnen List
• Typen, bei denen die Typen collectionDataType mit beginnen Array
• Primitive .NET-Arrays wie int[], string[], bool[], double[], decimal[], long[]

Halten Sie die Arbeit pro Element idempotent und kurzlebig. Verwenden Sie die Abschnitte Ausgaben und Variablen aktualisieren, wenn Sie Ergebnisse nach Abschluss aller Iterationen in einer einzigen Variable sammeln müssen.

So fügen Sie einen Multi-Instanz-Marker hinzu

Wichtig:

Konfigurieren Sie die Aktion der Aufgabe, bevor Sie sie in eine Mehrfachinstanz konvertieren. Die Mehrfachinstanzkonfiguration bindet sich in dem Moment, in dem Sie den Marker anwenden, an die Ausgaben der Aufgabe. Wenn zu diesem Zeitpunkt keine Aktion ausgewählt ist, wird die Bindung an den Standard-Ausgabeplatzhalter der Aufgabe und nicht an die tatsächliche Ausgabe der Aktion gebunden – und die spätere Auswahl einer Aktion aktualisiert diese Bindung nicht.Jede Iteration schreibt dann in eine ungebundene Ausgabe und erzeugt null Einträge in der aggregierten Variablen zur Laufzeit. Wenn Sie die Aufgabe zunächst in eine Mehrfachinstanz konvertiert haben, finden Sie unter „Aggregierte Variable enthält NULL-Werte“ Informationen zum Zurücksetzen und erneuten Anwenden.

1. Wählen Sie eine Aufgabe auf der Arbeitsfläche aus und konfigurieren Sie im „Eigenschaftenbereich“ ihre Aktion. Bestätigen Sie, dass der Abschnitt „Ausgaben“ die von Ihnen ausgewählte Aktion widerspiegelt – z. B. macht eine Agent-Aktion eine typisierte response Ausgabe und eine Error Ausgabe verfügbar.Fahren Sie erst fort, wenn der Abschnitt „Ausgaben“ mit der Aktion übereinstimmt.

2. In the element toolbar above the task, select Iteration.

   

3. Wählen Sie Sequenzielle Mehrfachinstanz oder Parallele Mehrfachinstanz aus.

   Der Marker erscheint unten am Rand der Aufgabeform.

4. Erweitern Sie im Eigenschaftenbereich „Multi-Instanz“.

   

5. Wählen Sie unter Elemente die Listenvariable aus, über die Sie iterieren möchten, z. B. vars.invoiceList.

   Dadurch wird Maestro mitgeteilt, welche Sammlung verarbeitet werden soll. Ohne einen Elementwert wird die Aufgabe einmal als normale Aufgabe ausgeführt, nicht einmal pro Element. Maestro erstellt eine Ausführung pro Element in der Liste.

6. Erweitern Sie optional die Fehlerbehandlung und aktivieren Sie Wiederholen bei Fehler, um einzelne Elementausführungen unabhängig voneinander zu wiederholen. Konfigurationsoptionen finden Sie unter Wiederholungen auf Elementebene.

Ergebnis

Die Aufgabe ist als Marker für Mehrfachinstanzen konfiguriert und iteriert einmal pro Element in der ausgewählten Listenvariable. Jede Iteration wird je nach gewähltem Markertyp sequenziell oder parallel ausgeführt.

Hinweis:

Mehrfachinstanz wird nur für Aufgaben unterstützt.Der von Ihnen ausgewählte Markertyp (sequenziell oder parallel) bestimmt die Ausführungsreihenfolge.

Verweisen auf das aktuelle Element

Der Abschnitt Mehrfachinstanz benötigt nur die Liste der Elemente – dort teilen Sie Maestro mit, welche Sammlung iteriert werden soll. Iterator-Ausdrücke befinden sich an einer anderen Stelle: im Abschnitt Eingaben der Aufgabe, wo Sie das aktuelle Element für jede Ausführung einer bestimmten Eingabe zuordnen.

Der verwendete Ausdruck hängt davon ab, ob der Marker direkt auf die Aufgabe angewendet wird oder ob die Aufgabe innerhalb eines Unterprozesses ausgeführt wird, der von einer Aufgabe mit mehreren Instanzen aufgerufen wird.

Szenario	Ausdruck	Wo sie verwendet werden soll
Direkt auf die Aufgabe angewendeter Marker	iterator.item	In den Eingabefeldern der Aufgabe
Aufgabe wird innerhalb eines Unterprozesses ausgeführt, der von einer Aufgabe mit mehrfachen Instanzen aufgerufen wird	iterator[0].item	In den Eingabefeldern der Unterprozessaufgabe

Hinweis:

Die [0] in iterator[0].item bezieht sich auf den äußersten Iterator-Scope, wenn eine Aufgabe innerhalb eines Unterprozesses ausgeführt wird. In der Standard-Mehrfachinstanz auf einer Ebene verwenden Sie immer [0] – es gibt keinen iterator[1].

Um das gesamte aktuelle Element zu übergeben, verwenden Sie iterator.item. Um eine einzelne Eigenschaft zu übergeben, verwenden Sie iterator.item.propertyName.Einige Beispiele:

• iterator.item.invoiceId
• iterator.item.customer.email
• { id: iterator.item.id, flags: ["recheck"] }

Verweisen Sie auf das aktuelle Element in einer Aufgabe

Wenn der Mehrfachinstanzenmarker direkt auf eine Aufgabe angewendet wird, verwenden Sie sie iterator.item im Abschnitt Eingaben des Eigenschaftenbereichs, um das aktuelle Element an jede Ausführung zu übergeben.

Verweis auf den Eigenschaftenbereich

• Aktion: Wählen Sie aus, wie die Aufgabe ausgeführt wird – Integration Service-Aktion, Agent-Aktion oder Keine nur für die Modellierung.

• Eingaben: Zeigt die von der ausgewählten Aktion definierten Parameter an. Legen Sie für jeden Parameter, den Sie mit dem aktuellen Listenelement ausfüllen möchten, seinen Wert auf iterator.item (das gesamte Element übergeben) oder iterator.item.propertyName (eine bestimmte Eigenschaft übergeben).

  

• Ausgaben: Definiert, was jede Iteration zurückgibt. Wenn eine Aktion für die Aufgabe konfiguriert ist, erscheinen hier automatisch die Ausgaben der Aktion (in der Regel response, plus Error für Agentaktionen), die jeweils über den Value-Chip an ihre Quelle gebunden sind.Zum Hinzufügen eines zusätzlichen Werts pro Iteration zusätzlich zu den Ausgaben der Aktion wählen Sie + Neu hinzufügen aus und geben Sie ihm einen Namen.Wenn die hier aufgeführten Einträge nicht widerspiegeln, was Ihre Aktion offenbart – z. B. wenn der Wert-Chip einen generischen Platzhaltertyp anstelle des tatsächlichen Ausgabetyps der Aktion zeigt – siehe Aggregierte Variable enthält NULL-Werte.

• Variablen aktualisieren: Gibt an, welche Prozessvariable die aggregierten Ausgaben nach Abschluss aller Iterationen speichert. Wählen Sie Variablenwert festlegen und wählen Sie die Zielvariable – zum Beispiel vars.validationResults. Die Variable enthält ein Array mit einem Eintrag pro Iteration: ein Array von Strings, wenn jede Iteration einen String zurückgibt, ein Array von Objekten, wenn jede Iteration ein Objekt zurückgibt.Im sequenziellen Modus folgen die Einträge der Eingabereihenfolge. Im Parallelmodus entspricht die Reihenfolge dem Abschluss der Iteration und ist nicht garantiert.

Verweisen Sie auf das aktuelle Element innerhalb eines Unterprozesses

Wenn eine Aufgabe innerhalb eines Unterprozesses ausgeführt wird, der von einer Aufgabe mit mehreren Instanzen aufgerufen wurde, ist das aktuelle Element nicht direkt als iterator.item verfügbar. Verwenden Sie stattdessen iterator[0].item in den Eingaben der Unterprozessaufgabe, um auf das Element zuzugreifen, das von der übergeordneten Mehrfachinstanzaufgabe übergeben wurde.

Verweis auf den Eigenschaftenbereich

• Aktion: Konfigurieren Sie, wie die Aufgabe mit dem externen System, der API oder dem Agent interagiert.

• Eingaben: Fügen Sie eine Eingabe für jeden Wert hinzu, den die Aufgabe benötigt. Legen Sie den Wert auf iterator[0].item fest, um das gesamte aktuelle Element zu übergeben, oder auf iterator[0].item.propertyName, um eine bestimmte Eigenschaft zu übergeben.

  Beispiel: Wenn Ihre Liste Objekte mit einem id Feld enthält, fügen Sie einen Eintrag im Abschnitt Eingaben des Eigenschaftenbereichs hinzu:

  • Name des Eingabefelds: currentItemId
  • Wert: iterator[0].item.id

  Ersetzen Sie .id durch den tatsächlichen Eigenschaftsnamen aus Ihren Listenobjekten.

Beispiele

Beispiel: Validieren einer Liste von Rechnungen

Dieses Beispiel zeigt, wie eine Dienstaufgabe so konfiguriert wird, dass sie einmal pro Rechnung in einer Liste ausgeführt wird.

1. Vorbereiten einer Listenvariable

1. Data Manager öffnen.
2. Variable erstellen:
   • Name: invoiceList
   • Typ: Array von Objekten oder Array von Strings
   • Standardwert: ["INV-001", "INV-002", "INV-003"]

2. Fügen Sie eine Service-Aufgabe hinzu und konfigurieren Sie die Aktion

1. Fügen Sie der Canvas eine Dienstaufgabe hinzu und nennen Sie sie Rechnung validieren.

2. Wählen Sie die Aufgabe und öffnen Sie dann den Abschnitt Aktion im Eigenschaftenbereich und konfigurieren Sie, welcher Agent für jede Rechnung ausgeführt wird:

   • Aktion: Wählen Sie Starten und auf Agent warten aus.
   • Agent: Wählen Sie den Agent aus, der für die Validierung von Rechnungen verantwortlich ist. Der Agent muss in Ihrem Mandanten bereits vorhanden sein – Sie können einen Agenten in Agent Builder erstellen.

   

3. Bestätigen Sie, dass der Abschnitt Ausgaben die Agenten-Aktion widerspiegelt – die response Ausgabe sollte mit ihrem tatsächlichen Ausgabetyp neben Error erscheinen.Fahren Sie erst fort, wenn dies passt.

3. Konvertieren Sie die Aufgabe in Mehrfachinstanz

1. With the task selected, open the element toolbar and select Select markers → Sequential multi-instance.
2. Erweitern Sie im Eigenschaftenbereich „Mehrfachinstanz“ und setzen Sie „Elemente“ auf vars.invoiceList.

4. Ordnen Sie das aktuelle Element einer Eingabe zu

Nachdem Sie Ihre Aktion ausgewählt haben, werden im Abschnitt Eingaben die von dieser Aktion definierten Parameter angezeigt – z. B. die Eingabeargumente Ihres RPA-Workflows oder die Parameter Ihres Agents.

Für jeden Parameter, den Sie mit dem aktuellen Listenelement füllen möchten, wählen Sie dessen Wertfeld aus und geben iterator.item: ein

• Verwenden Sie iterator.item, um das gesamte aktuelle Element zu übergeben – zum Beispiel den String "INV-001", wenn Ihre Liste Strings enthält.
• Verwenden Sie iterator.item.propertyName, um eine bestimmte Eigenschaft zu übergeben – z. B. iterator.item.id, wenn Ihre Liste Objekte enthält.

5. Debug den Prozess

1. Wählen Sie Debuggen → Schritt-für-Schritt-Debuggen aus.
2. Maestro führt die Funktion Rechnung validieren einmal pro Listenelement aus.

Ergebnis

Der Ausführungspfad zeigt eine Ausführung pro Rechnung, die jeweils mit ihrem Elementwert beschriftet ist.

Wenn Sie alle Elemente gleichzeitig statt nacheinander ausführen möchten, wählen Sie in Schritt 2 die Option Parallele Mehrfachinstanz aus. Siehe auch das folgende Fan-out-Beispiel.

Beispiel: Fan-out und Ergebnisse sammeln

Szenario: Sie erhalten eine Liste von Rechnungs-IDs von einer externen API und müssen jede einzelne unabhängig voneinander validieren und dann die aggregierten Ergebnisse in einem nachgelagerten Schritt verwenden.

1. Sorgen Sie dafür, dass eine Listenvariable – z. B. vars.invoiceIds – durch einen vorherigen Schritt ausgefüllt ist, z. B. eine Service-Aufgabe, die eine externe API aufruft.
2. Fügen Sie eine Service-Aufgabe mit dem Namen Rechnung validieren hinzu und konfigurieren Sie für die reguläre Aufgabe die Aktion, die eine einzelne Rechnung validiert. Bestätigen Sie, dass der Abschnitt Ausgaben die Aktion widerspiegelt – der Eintrag response sollte den tatsächlichen Ausgabetyp der Aktion anzeigen.
3. With the task selected, select Select markers → Parallel multi-instance.
4. Legen Sie im Abschnitt Mehrfachinstanz die Option „Elemente“ auf vars.invoiceIds fest.
5. Ordnen Sie im Abschnitt Eingaben iterator.item dem Parameter Rechnungs-ID Ihrer Aktion zu – legen Sie beispielsweise die Eingabe invoiceId auf iterator.item fest.
6. Vergewissern Sie sich im Abschnitt Ausgaben, dass die Ausgabe der Aktion response aufgelistet ist und an das Ergebnis der Aktion gebunden ist. Wenn Sie einen zusätzlichen aggregierten Wert pro Iteration benötigen, wählen Sie + Neu hinzufügen aus und definieren Sie ihn. Wenn die aufgeführten Ausgaben nicht mit dem übereinstimmen, was Ihre Aktion offenbart, wurde der Marker angewendet, bevor die Aktion konfiguriert wurde; siehe Aggregierte Variable enthält NULL-Werte.
7. Wählen Sie im Abschnitt Variablen aktualisieren die Option Variablenwert festlegen und wählen Sie die Variable aus, in der die aggregierten Ergebnisse gespeichert werden sollen – z. B. vars.validationResults. Nach Abschluss aller Iterationen enthält diese Variable einen Eintrag pro Rechnung – ein Array von Strings, wenn Ihre Aktion einen String zurückgibt, oder ein Array von Objekten, wenn sie ein Objekt zurückgibt.

Ergebnis

Die Aufgabe mit mehreren Instanzen wird einmal pro Rechnungs-ID parallel ausgeführt und die aggregierten Ergebnisse werden nach Abschluss aller Iterationen in der konfigurierten Variable gesammelt.

Runtime-Verhalten

1. Fan-out/Fan-in: Maestro erstellt eine Aktivitätsinstanz pro Element und vervollständigt die Gruppe, wenn alle Instanzen fertig sind.
2. Bestellung: Garantiert im sequenziellen Modus; nicht garantiert im parallelen Modus.
3. Gleichzeitigkeit: Im Parallelmodus werden Elemente gleichzeitig ausgeführt, vorbehaltlich Plattformlimits und Ressourcenverfügbarkeit.
4. Fehler: Das Ergebnis jedes Elements ist unabhängig. Definieren Sie nachgelagerte Logik zur Behandlung von Teilfehlern – z. B. Fortsetzen, Wiederholen oder Anhalten basierend auf einem Schwellenwert.
5. Beobachtbarkeit: Jede Elementausführung wird einzeln im Ausführungspfad nachverfolgt, wobei Status und Ergebnisse pro Element angezeigt werden.

Fehlersuche und ‑behebung

Aggregierte Variable enthält NULL-Werte

Die von Update variables erstellte aggregierte Variable enthält null für jede Iteration (z. B. [null, null, null]), auch wenn jede Iteration erfolgreich ausgeführt wurde.

Dies geschieht, wenn die Aufgabe in eine Mehrinstanz konvertiert wurde, bevor ihre Aktion ausgewählt wurde. Die Mehrfachinstanzkonfiguration ist an den Standard-Ausgabenplatzhalter der Aufgabe und nicht an die tatsächliche Ausgabe der Aktion gebunden, und die anschließende Auswahl einer Aktion aktualisiert diese Bindung nicht. Jede Iteration schreibt in eine ungebundene Ausgabe und der Aggregator zeichnet null auf.

So beheben Sie eine vorhandene Aufgabe:

1. In the element toolbar, select Select markers and remove the multi-instance marker to convert the task back to a regular task.
2. Bestätigen Sie, dass die Aktion ausgewählt ist und dass der Abschnitt Ausgaben die Aktion widerspiegelt (z. B. response durch die Aktion typisiert, plus ErrorAgent-Aktionen).
3. Re-apply the marker with Select markers → Sequential multi-instance or Parallel multi-instance.
4. Überprüfen Sie im Abschnitt Ausgaben, ob die Einträge noch mit den Ausgaben der Aktion übereinstimmen.

Um dies bei neuen Aufgaben zu verhindern, konfigurieren Sie die Aktion immer, bevor Sie die Aufgabe in eine Mehrfachinstanz konvertieren.

Die Elementeingabe wird ignoriert und die Aufgabe wird einmal ausgeführt

Die Aufgabe wird einmalig ausgeführt und der Wert von Elementen wird als reguläre Eingabe behandelt.

Dies geschieht, wenn die an Items übergebene Variable keiner der unterstützten Sammlungstypen ist. Überprüfen Sie den Typ der Variablen in Data Manager anhand der unterstützten Sammlungstypen. Wenn Sie die Liste als einfachen String definiert haben, konvertieren Sie sie in einen Array von Strings oder einen Array von Objekten.

Ausgabeneinträge spiegeln nicht die Ausgaben der Aktion wider.

Der Abschnitt Ausgaben zeigt nicht die Einträge an, die Sie von der ausgewählten Aktion erwarten – z. B. sollte eine Agent-Aktion response und Error bereitstellen, aber es erscheint nur ein generischer response Platzhalter.

Die Ausgaben wurden erfasst, bevor die Ausbreitung der Aktionsauswahl abgeschlossen war. Entfernen Sie den Mehrfachinstanzmarker über Element ändern → reguläre Aufgabe, bestätigen Sie, dass der Abschnitt „Ausgaben“ die Aktion widerspiegelt, und wenden Sie den Marker dann erneut an.

Best Practices

1. Überprüfen Sie die Sammlung vor dem Fan-out – achten Sie auf leere, nullwertige oder übermäßig große Listen.
2. Halten Sie die Arbeit pro Element kurzlebig und fehlertolerant. Fügen Sie gegebenenfalls Wiederholungen hinzu.
3. Aggregieren Sie nur das, was Sie benötigen. Große Aggregationen können die Leistung und Lesbarkeit beeinträchtigen.
4. Formulieren Sie die Erfolgskriterien explizit.Fügen Sie nach der Mehrfachinstanzaufgabe ein exklusives Gateway hinzu, das die aggregierte Ausgabevariable auswertet – z. B. nur dann zum nächsten Schritt weiterleiten, wenn die Anzahl der erfolgreichen Ergebnisse Ihren Schwellenwert erfüllt.

Hinweis:

Die parallele Mehrfachinstanz führt Elemente in 50er Stapeln aus.Wenn jedes Element ein großes oder komplexes Objekt ist – mehrere Schlüssel-Wert-Paare oder verschachtelte Strukturen –, halten Sie auch die Gesamtsammlungsgröße unter 50, da die Elementgröße beeinflusst, wie viele gleichzeitig aufrechterhalten werden können.

Lesen Sie Marker (BPMN Primer) für Notation und konzeptionelle Anleitung sowie BPMN-Unterstützung für die vollständige Liste der BPMN-Elemente, die in Maestro unterstützt werden.

Arbeiten Sie in einem Teilprozess oder einer Aufrufaktivität? Informationen zum Variablen-Scoping, zu Eingabe-/Ausgabe-Zuordnungen und zu Endereignisvariablen finden Sie unter Unterprozesse.