Maestro user guide

Multi-instance markers

link

• Validating each invoice in a list of invoice IDs
• Enriching a set of records by calling an external API per record
• Sending a notification to each recipient in a list

• 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
• Types where collectionDataType starts with List
• Types where collectionDataType starts with Array
• Primitive .NET arrays such as int[], string[], bool[], double[], decimal[], long[]

1. Select a task on the canvas.

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

   

3. Choose Sequential multi-instance or Parallel multi-instance.

   The marker appears at the bottom of the task shape.

   

4. In the Properties panel, expand Multi-instance.

   

5. In Items, select the list variable you want to iterate over — for example, vars.invoiceList.

   This tells Maestro which collection to process. Without an Items value, the task runs once as a normal task, not once per element. Maestro creates one execution per element in the list.

6. Optionally, expand Error handling and enable Retry on failure to retry individual item runs independently. For configuration options, see Element-level retries.

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

Reference the current item in a task​

• Action: Choose how the task runs — Integration Service action, agent action, or None for modeling only.

• Inputs: Shows the parameters defined by the selected action. For each parameter you want to populate with the current list item, set its value to iterator.item (to pass the whole element) or iterator.item.propertyName (to pass a specific property).

  

• Outputs: Defines what each iteration returns. Select + Add new and give the output a name — for example, validationResult. Set it to the value your action returns. After all iterations complete, Maestro collects each iteration's output and makes it available through Update variables.

• Update variables: Specifies which process variable stores the collected outputs after all iterations finish. Select Set variable value and choose the target variable — for example, vars.validationResults. The variable will contain one entry per iteration.

Reference the current item inside a subprocess​

• Action: Configure how the task interacts with the external system, API, or agent.

• Inputs: Add an input for each value the task needs. Set the value to iterator[0].item to pass the whole current element, or iterator[0].item.propertyName to pass a specific property.

  Example — if your list contains objects with an id field, add an entry in the Inputs section of the Properties panel:

  • Input field name: currentItemId
  • Value: iterator[0].item.id

  Replace .id with the actual property name from your list objects.

Example: Validate a list of invoices​

1. Prepare a list variable​

1. Open Data Manager.
2. Create a variable:
   • Name: invoiceList
   • Type: Array of Objects or Array of Strings
   • Default value: ["INV-001", "INV-002", "INV-003"]

2. Add and configure a Service task​

1. Add a Service task to the canvas and name it Validate invoice.
2. Select the task, then in the element toolbar select Change element and choose Sequential multi-instance.
3. In the Properties panel, expand Multi-instance.
4. In Items, enter vars.invoiceList.

3. Configure the implementation​

• Action: Select Start and wait for agent.
• Agent: Select the agent responsible for validating invoices. The agent must already exist in your tenant — you can create one in Agent Builder.

4. Map the current item to an input​

• Use iterator.item to pass the entire current element — for example, the string "INV-001" if your list contains strings.
• Use iterator.item.propertyName to pass a specific property — for example, iterator.item.id if your list contains objects.

5. Debug the process​

1. Select Debug → Debug step-by-step.
2. Maestro runs Validate invoice once per list item.

Example: Fan-out and collect results​

1. Make sure a list variable — for example, vars.invoiceIds — is populated by a previous step, such as a Service task that calls an external API.

2. Add a Service task named Validate invoice. Select the task, choose Change element, and select Parallel multi-instance.

3. In the Multi-instance section, set Items to vars.invoiceIds.

4. In the Inputs section, map iterator.item to the invoice ID parameter of your action — for example, set the invoiceId input to iterator.item.

5. In the Outputs section, select + Add new and name the output — for example, validationResult. Set it to the value your action returns for each invoice.

6. In the Update variables section, select Set variable value and choose the variable to store the aggregated results — for example, vars.validationResults. After all iterations finish, this variable contains one entry per invoice.

   

1. Fan-out / fan-in: Maestro creates one activity instance per item and completes the group when all instances finish.
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: Each item's result is independent. Define downstream logic to handle partial failures — for example, continue, retry, or stop based on a threshold.
5. Observability: Each item run is tracked individually in the Execution trail, showing per-item status and outcomes.

1. Validate the collection before fan-out — check for 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 affect performance and readability.
4. Make success criteria explicit. After the multi-instance task, add an Exclusive gateway that evaluates the aggregated output variable — for example, route to the next step only if the number of successful results meets your threshold.