Multi-instance implementation

Use markers to configure the execution of a certain task type to create multiple executions of that task by iterating over a List variable. Visit Markers in the BPMN Primer chapter for more details.

Con cualquier tipo de tarea seleccionada, selecciona Cambiar elemento y elige uno de los tipos de marcadores.

Cuando usarlo

Use multi‑instance execution to fan out an activity across a collection—for example, validating a list of invoice IDs, enriching records, or sending per‑recipient notifications. This pattern scales better than a manual loop and preserves observability.

Configuración

• Collection (required): A variable or expression that evaluates to a list/array. Each item should be independently processable.
• Item alias (iterator variable): The name that represents the current element during iteration. If you leave it blank, use the default alias provided by the product (for example, item). You can reference the alias in any input field of the activity.
• Using the item in inputs:
  • Pass the whole item: set an input to the alias itself (for example, item).
  • Pass a property of the item: reference a field on the alias (for example, item.id or item["invoiceId"]).
  • Build a new object from the item: compose an object using item fields (for example, { id: item.id, total: item.amount }).
  • Transform the item: apply an expression that returns the shape the activity expects (for example, toUpper(item.email)).
• Iterator expression (when available): Some activities provide a dedicated field to map the current item into the exact per‑run input value. Use it when the activity expects a single value rather than the full item. Examples: item.invoiceId, item.customer.email, or .{ id: item.id, flags: ["recheck"] }.
• Mode: Sequential (ordered, one by one) or Parallel (concurrent).
• Aggregation (optional): Combine per-item outputs into one result. You can collect results into a list, create item-to-result pairs, or apply a reduction expression.

Soporte para bucles

Use multi-instance to replace manual loops. Treat the collection as the loop boundary. Sequential mode processes items in order and waits for each to finish before the next starts. Parallel mode starts many items at once and completes when all finish or when your stop condition is met. Keep per-item work idempotent and short-lived. Use Aggregation if you need a single combined output.

Comportamiento de runtime

1. Fan‑out / fan‑in: Maestro creates one activity instance per item and completes the group when all instances finish (or earlier, if you use a custom stop policy downstream).
2. Ordering: Guaranteed in Sequential mode; not guaranteed in Parallel mode.
3. Concurrency: Parallel mode runs items concurrently, subject to platform limits and resource availability.
4. Failures: Treat each item’s result independently. Downstream logic should define how to handle partial failures (e.g., continue, retry, or stop based on thresholds).
5. Observability: Each item run is tracked, enabling per‑item status and aggregated outcomes.

Ejemplo

Scenario: You receive a list of invoice IDs from an external API and must validate each invoice via a second API.

Plan:

1. Obtain a dynamic list of invoice IDs (from a previous step or external interrogation).
2. Apply a Parallel multi‑instance marker to the validation activity to fan out one action per invoice.
3. Use Aggregation to produce a single combined output (for example, a list of {invoiceId, isValid, errors}) for downstream steps.

Mejores prácticas

1. Validate the collection before fan‑out (empty, null, or excessively large lists).
2. Keep per‑item work short‑lived and fault‑tolerant; add retries where appropriate.
3. Aggregate only what you need. Large aggregations can impact performance and readability.
4. Make success criteria explicit (e.g., proceed if ≥95% items succeed).

Note: Currently, the parallel multi-instance executes elements in batches of 50.

Read Markers (BPMN Primer) for notation and conceptual guidance, and BPMN support for the full list of BPMN elements supported in Maestro.