多实例标记

概述

使用标记配置任务，使“列表”变量中的每个元素运行一次，从而创建多次顺序或并行执行。访问“BPMN 入门”章节中的“标记”，获取标记和概念指导。

何时使用多实例标记

当您有一个项目列表并且需要为每个项目运行一次同一任务时，请使用多实例标记 — 例如：

• 验证发票 ID 列表中的每个发票
• 通过为每条记录调用外部 API，丰富一组记录
• 向列表中的每位收件人发送通知

如果没有标记，您需要使用序列流构建手动循环，这样更难读取和跟踪。多实例标记有助于保持流程图的简洁，并在执行追踪记录中查看每个项目的状况。每个项目的运行情况都会单独显示，并显示各自的状态和输出。

如果注重顺序或每次运行都依赖于上一次运行，请使用“顺序”模式。如果项目相互独立且希望达到更大的吞吐量，请使用“并行”模式。

Supported collection types

Maestro treats the following collection types as loopable for multi-instance execution. If your variable is one of these types, you can use it directly in the Items field:

• 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
• collectionDataType以 List为开头的类型
• collectionDataType以 Array为开头的类型
• 原始 .NET 数组，例如 int[]、string[]、、bool[]、double[]、decimal[]、 long[]

保持每个项目的工作幂等且持续时间短。如果您需要在所有迭代完成后将结果收集到单个变量，请使用“输出”和“更新变量”部分。

如何添加多实例标记

重要提示：

Configure the task's Action before converting it to multi-instance. The multi-instance configuration binds to the task's Outputs at the moment you apply the marker. If no action is selected at that point, the binding is tied to the task's default output placeholder rather than the action's actual output — and selecting an action afterwards does not refresh this binding. Each iteration then writes to an unbound output, producing null entries in the aggregated variable at runtime. If you already converted the task to multi-instance first, see Aggregated variable contains nulls for the unset and re-apply workaround.

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. 在任务上方的元素工具栏中，选择“更改元素”。

   

3. 选择“顺序多实例”或“并行多实例”。

   标记将显示在任务形状的底部。

   

4. 在“属性”面板中，展开“多实例”。

   

5. 在“项目”中，选择您要迭代的列表变量，例如 vars.invoiceList。

   这会指示 Maestro 要处理哪个集合。若无“项目”值，任务将作为常规任务运行一次，而非每个元素运行一次。Maestro 为列表中的每个元素创建一次执行。

6. 可以选择性地展开“错误处理”并启用“失败时重试”，以独立重试各个项目运行。有关配置选项，请参阅“元素级重试”。

备注：

只有任务支持多实例。您选择的标记类型（顺序或并行）将决定执行顺序。

引用当前项目

“多实例”部分仅需要“项目”列表，您可以在其中指示 Maestro 要迭代哪个集合。迭代器表达式会进入不同的位置：任务的“输入”部分，每次运行时，都会将当前项目映射到特定输入。

您使用的表达式取决于标记是直接应用于任务，还是任务在从多实例任务调用的子流程中运行。

场景	表达式	使用位置
直接应用于任务的标记	iterator.item	在任务的“输入”字段中
任务在从多实例任务调用的子流程中运行	iterator[0].item	在子流程任务的“输入”字段中

备注：

iterator[0].item 中的 [0] 是指任务在子流程中运行时的最外部的迭代器作用域。在标准单级多实例中，您将始终使用 [0]，没有 iterator[1]。

要传递当前的整个元素，请使用 iterator.item。要传递单个属性，请使用 iterator.item.propertyName。以下是相关示例:

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

Reference the current item in a task

将多实例标记直接应用于任务时，请在“属性”面板的“输入”部分使用 iterator.item，将当前元素传递到每次运行。

“属性”面板引用

• 操作：选择任务的运行方式（Integration Service 操作、智能体操作，如果仅用于建模，则为“无”）。

• 输入：显示由所选操作定义的参数。对于要填充当前列表项目的每个参数，如需传递整个元素，请将其值设置为 iterator.item，如需传递特定属性，请设设置为 iterator.item.propertyName。

  

• 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

当任务在从多实例任务调用的子流程中运行时，当前项目无法直接作为 iterator.item 使用。相反，请在子流程任务的“输入”中使用 iterator[0].item，访问从父多实例任务传递的元素。

“属性”面板引用

• 操作：配置任务与外部系统、API 或智能体交互的方式。

• 输入：为任务所需的每个值添加输入。如需传递当前的整个元素，请将值设置为 iterator[0].item，如需传递特定属性，则设置为 iterator[0].item.propertyName。

  示例 — 如果您的列表包含带有 id 字段的对象，请在“属性”面板的“输入”部分添加一个条目：

  • 输入字段名称：currentItemId
  • 值: iterator[0].item.id

  将 .id 替换为列表对象中的实际属性名称。

示例

示例：验证发票列表

此示例显示如何配置“服务”任务，以便为列表中的每个发票运行一次任务。

1. 准备一个列表变量

1. 打开“数据管理器”。
2. 创建变量：
   • 名称：invoiceList
   • 类型：对象数组或字符串数组
   • 默认值：["INV-001", "INV-002", "INV-003"]

2. Add a Service task and configure the action

1. 将“服务”任务添加到画布，并将其命名为“验证发票”。

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

   • 操作：选择“开始并等待智能体“。
   • 智能体：选择负责验证发票的智能体。智能体必须已存在于您的租户中。您可以在 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. 将当前项目映射到输入

选择操作后，“输入”部分将显示该操作定义的参数，例如 RPA 工作流的输入参数或智能体的参数。

For each parameter you want to populate with the current list item, select its value field and enter iterator.item:

• 如需传递当前的整个元素，请使用 iterator.item，例如字符串 "INV-001"（如果您的列表包含字符串）。
• 如需传递特定属性，请使用 iterator.item.propertyName，例如 iterator.item.id（如果您的列表包含对象）。

5. 调试流程

1. 选择“调试”→“分步调试”。
2. Maestro 会为每个列表项目运行一次“验证发票”。

结果：执行追踪记录会显示每张发票运行一次，每次都会标记其项目值。

To run all items concurrently instead of sequentially, choose Parallel multi-instance in step 2. See also the fan-out example below.

示例：扇出并收集结果

Scenario: You receive a list of invoice IDs from an external API and need to validate each one independently, then use the aggregated results in a downstream step.

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. 扇出/扇入：Maestro 为每个项目创建一个活动实例，并在所有实例完成后完成组。
2. 排序：在“顺序”模式下保证；在“并行”模式下不保证。
3. 并发：并行模式会并发运行项目，受平台限制和资源可用性的约束。
4. 失败：每个项目的结果都是独立的。定义下游逻辑，用于处理部分失败（例如，根据阈值继续、重试或停止）。
5. 可观察性：每次项目运行都在执行追踪记录中单独跟踪，显示每个项目的状态和结果。

故障排除

Aggregated variable contains nulls

The aggregated variable produced by Update variables contains null for every iteration (for example, [null, null, null]) even though each iteration ran successfully.

This happens when the task was converted to multi-instance before its Action was selected. The multi-instance configuration is bound to the task's default output placeholder rather than the action's actual output, and selecting an action afterwards does not refresh this binding. Each iteration writes to an unbound output and the aggregator records null.

To fix an existing task:

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.

To prevent this on new tasks, always configure the Action before converting the task to multi-instance.

Items input is ignored and the task runs once

The task runs a single time and the Items value is treated as a regular input.

This happens when the variable passed to Items is not one of the supported collection types. Check the variable's type in Data Manager against Supported collection types. If you defined the list as a plain string, convert it to Array of Strings or Array of Objects.

Outputs entries do not reflect the action's outputs

The Outputs section does not show the entries you expect from the selected action — for example, an agent action should expose response and Error, but only a generic response placeholder appears.

The Outputs were captured before the action selection finished propagating. Unset the multi-instance marker via Change element → regular task, confirm the Outputs section reflects the action, then re-apply the marker.

最佳实践

1. 在扇出之前验证集合（检查空、null 或过大的列表）。
2. 保持每个项目的工作时间短且具有容错功能。在适当的情况下添加重试。
3. 仅聚合您需要的内容。 大型聚合可能会影响性能和可读性。
4. 明确成功标准。多实例任务完成后，添加“排他网关”，用于评估聚合输出变量，例如，只有成功结果数量达到阈值时，才会路由到下一个步骤。

备注：

Parallel multi-instance executes elements in batches of 50. If each item is a large or complex object — multiple key-value pairs or nested structures — keep the total collection size below 50 as well, since item size affects how many can be sustained concurrently.

阅读“标记（BPMN 入门）”以获取标记和概念指导，阅读“BPMN 支持”以了解 Maestro 中支持的 BPMN 元素完整列表。

在子流程或调用活动中工作？ 有关变量作用域、输入/输出映射和“结束事件”变量，请参阅“子流程”。