Marqueurs multi-instances

Vue d'ensemble (Overview)

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.

Quel que soit le type de tâche sélectionné, sélectionnez Change element (Modifier l'élément) et choisissez un des types de marqueurs.

How to add a multi-instance marker

You can turn any supported task into a multi-instance task from the BPMN designer:

1. Select a task on the canvas.
2. In the element toolbar above the task, select Change element.
3. Choose the multi-instance marker (sequential or parallel icon).
   • This attaches the BPMN marker to the task.
4. Open the Properties panel and expand the Multi-instance section to configure the Items list.

Remarque :

• In Maestro, adding the BPMN marker does not expose extra controls like alias or mode; the only configuration appears in the Multi-instance section, the Items field.
• The marker is purely declarative; Maestro determines execution mode automatically.
• Multi-instance is supported only for tasks (not subprocesses).

Quand l’utiliser

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.

Configuration

• Select the task that you want to run for each element of a list.
• In the Properties panel, expand Multi-instance.
• In Items, choose the list variable that contains the elements you want to iterate over (for example, vars.invoiceList). Maestro creates one execution per list element and manages iteration automatically. You can reference the current element in inputs by using its index or property (for example, vars.invoiceList[index].id).
• (Optional) Expand the Error handling section and toggle Retry on failure if you want Maestro to retry individual items that fail.
• Run or debug the process to view one activity instance per list element in the execution trail.
• 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"] }.
  Iterators are variables that represent individual items when a multi-instance task processes a collection. Use the correct syntax depending on where the iteration occurs:

  • iterator.item — Use when the multi-instance marker is applied directly on a task.
    
    
    
    

    Panneau propriétés

    Action: Choose how the task runs. For a Service task, select an Integration Service action, an agent action, or leave it set to None when the task is used only for modeling.

    Inputs: Provide values the task needs for each iteration. Use this section to pass the current element or its fields.

    Exemple :

    • Input: invoiceId
    • Value: vars.invoiceList[index].id

    Outputs: Return data from each subprocess execution. Maestro aggregates output values when the process completes.

    Update variables: Update workflow-level variables after each iteration or after the entire Sub-process finishes.

  • iterator[0].item — Use when working inside a subprocess that’s called from a multi-instance task.
    
    
    
    

    Panneau propriétés

    Action: Under implementation, in the Action field, choose how the subprocess interacts with an external system, agent, or API (if applicable). For expanded Sub-processes used only for modeling, leave Action set to None.

    Entrées

    Map data into the subprocess, including the current list element or its properties.

    Exemple :

    • Input: currentItemId
    • Value: vars.itemsToProcess[index].id

Example: Validate a list of invoices using multi-instance execution

This example shows how to configure a Service task to run once for each invoice in a list.

1. Prepare a list variable
   1. Ouvrez le Gestionnaire de données.
   2. Create a variable:
      • Name:invoiceList
      • Type: Array of Objects or Array of Strings
      • Example value:["INV-001","INV-002","INV-003"]
2. Add a Service task
   1. Add a Service task and name it Validate invoice.
   2. Open the Properties panel and expand the Multi-instance section.
   3. In Items, select invoiceList.
3. Use the current item in inputs

   In the Inputs section:

   For example, set InvoiceId as vars.invoiceList[index]
   If the list contains objects rather than strings: Use vars.invoiceList[index].Id
4. Configure implementation

   In the Implementation section, select:

   • Action: Démarrer et attendre un agent
   • Agent: your invoice validation agent
5. Debug the process
   1. Sélectionnez Déboguer étape par étape.
   2. You will see one execution of the Validate invoice task per list item.
   3. The Execution trail displays each per-item run separately.

1. Add a Service task called Validate invoice to your process.
2. Select Change element, and in the top-right corner of the prompt, choose Parallel multi-instance.
3. In the Properties panel, expand the Multi-instance section.
4. In Items choose the list variable that contains the elements you want to iterate over (for example vars.invoiceList). Maestro creates one execution per list element and manages iteration automatically. You can reference the current element in inputs by using its index or property (for example, vars.invoiceList[index].id).
5. Run or debug the process to view one activity instance per list element in the Execution trail.

Prise en charge des boucles

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.

Comportement du 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.

Exemple

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.

Meilleures pratiques

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.

Working in a subprocess or call activity? For variable scoping, input/output mappings, and End Event variables, read Subprocesses.