Maestro user guide

Overview​

How to add a multi-instance marker​

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.

Notes

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

When to use it​

• validating a list of invoice IDs
• enriching records
• sending per-recipient notifications

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 (e.g., vars.invoiceList).
  Maestro creates one execution per list element.
  Reference the current item using the index or its properties (vars.invoiceList[index].id).
• (Optional) Expand Error handling and toggle Retry on failure to retry individual item runs.
• Run or debug the process to view one activity instance per list element in the execution trail.

Iterator expression (when available)​

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

iterator.item — when a task has a multi-instance marker applied​

• Action: Choose how the task runs (Integration Service action, agent action, or None for modeling).
• Inputs: Provide values for each iteration.
  Example:
  • Input: invoiceId
  • Value: vars.invoiceList[index].id
• Outputs: Maestro aggregates all outputs automatically.
• Update variables: Choose what to update after each iteration or after the subprocess finishes.

iterator[0].item — when working inside a subprocess called from a multi-instance task​

• Action: Configure how the subprocess interacts with the external system, API, or agent.
• Inputs: Map the current element or its properties.

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

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

1. Prepare a list variable​

1. Open Data Manager.
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 Properties panel, expand Multi-instance.
3. In Items, select invoiceList.

3. Use the current item in inputs​

• Example: set InvoiceId = vars.invoiceList[index].
• If the list contains objects:
  Use vars.invoiceList[index].Id.

4. Configure implementation​

• Action: Start and wait for agent
• Agent: your invoice validation agent

5. Debug the process​

1. Select Debug step-by-step.
2. You will see one execution of Validate invoice per list item.
3. The Execution trail displays each item’s run separately.

Parallel multi-instance example​

1. Add a Service task named Validate invoice.
2. Select Change element → choose Parallel multi-instance.
3. In Properties panel, expand Multi-instance.
4. In Items, choose the list variable (e.g., vars.invoiceList).
5. Debug the process to view one activity instance per list element in the Ex

Looping support​

Runtime behavior​

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.

Example​

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.

   

Best practices​

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).