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 and, in the Properties panel, configure its Action. Confirm that the Outputs section reflects the action you selected — for example, an agent action exposes a typed response output and an Error output. Continue only after the Outputs section matches the action.

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. When an action is configured on the task, the action's outputs (typically response, plus Error for agent actions) appear here automatically, each bound to its source via the Value chip. To add an extra value per iteration on top of the action's outputs, select + Add new and give it a name. If the entries listed here do not reflect what your action exposes — for example, the Value chip shows a generic placeholder type instead of the action's actual output type — see Aggregated variable contains nulls.

• Update variables: Specifies which process variable stores the aggregated outputs after all iterations finish. Select Set variable value and choose the target variable — for example, vars.validationResults. The variable holds an array with one entry per iteration: an array of strings if each iteration returns a string, an array of objects if each iteration returns an object. In Sequential mode, the entries follow input order. In Parallel mode, the order matches iteration completion and is not guaranteed.

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 a Service task and configure the action​

1. Add a Service task to the canvas and name it Validate invoice.

2. With the task selected, open the Action section in the Properties panel and configure which agent runs for each invoice:

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

   

3. Confirm the Outputs section reflects the agent action — the response output should appear with its actual output type, alongside Error. Continue only after this matches.

3. Convert the task to multi-instance​

1. With the task selected, open the element toolbar and select Change element → Sequential multi-instance.
2. In the Properties panel, expand Multi-instance and set Items to vars.invoiceList.

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 and, on the regular task, configure the Action that validates a single invoice. Confirm that the Outputs section reflects the action — the response entry should show the action's actual output type.

3. With the task selected, choose Change element → Parallel multi-instance.

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

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

6. In the Outputs section, verify that the action's response output is listed and bound to the action's result. If you need an additional aggregated value per iteration, select + Add new and define it. If the listed outputs do not match what your action exposes, the marker was applied before the action was configured; see Aggregated variable contains nulls.

7. 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 — an array of strings if your action returns a string, or an array of objects if it returns an object.

   

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.

Aggregated variable contains nulls​

1. In the element toolbar, select Change element and convert the task back to a regular task.
2. Confirm the action is selected and that the Outputs section reflects the action (for example, response typed by the action, plus Error for agent actions).
3. Convert the task to multi-instance again with Change element → Sequential multi-instance or Parallel multi-instance.
4. In the Outputs section, verify the entries still match the action's outputs.

Items input is ignored and the task runs once​

Outputs entries do not reflect the action's outputs​

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.