多实例标记

概述

使用标记配置特定任务类型的执行，通过遍历“列表”变量创建多次执行。有关更多详细信息，请参阅“BPMN 入门”章节中的“标记”。

选定任何任务类型后，选择“更改元素”，然后选择一种标记类型。

如何添加多实例标记

您可以从 BPMN 设计器中将任何受支持的任务转换为多实例任务：

1. 在画布上选择任务。
2. 在任务上方的元素工具栏中，选择“更改元素”。
3. 选择多实例标记（按顺序或并行图标）。
   • 这会将 BPMN 标记附加到任务。
4. 打开“属性”面板，然后展开“多实例”部分，以配置“项目”列表。

注意

• 添加 BPMN 标记不会显示额外的控件，例如别名或模式；唯一的配置将显示在“项目”下的“多实例”部分中。
• 标记是声明式的；Maestro 会自动确定执行模式。
• 多实例仅支持任务，不支持子流程。

何时使用

使用多实例执行来跨集合散发活动，例如：

• 正在验证发票 ID 的列表
• 丰富记录
• 按收件人发送通知

此模式的扩展性优于手动循环，并可保留可观察性。

配置

• 选择要为列表的每个元素运行的任务。
• 在“属性”面板中，展开“多实例”。
• 在“项目”中，选择包含要迭代的元素的列表变量（例如vars.invoiceList）。
  Maestro 为每个列表元素创建一次执行。
  使用索引或其属性 () 引用当前项目。
• （可选）展开“错误处理”，并在失败时切换到“重试”，以重试单个项目的运行。
• 运行或调试流程，在执行追踪记录中每个列表元素查看一个活动实例。

迭代器表达式（当可用时）

某些活动提供了一个专用字段，用于将当前项目映射到每次运行的精确输入值。

示例:

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

当多实例任务处理集合时，迭代器表示单个项目。Processes

正确的语法取决于迭代发生的位置：

iterator.item — 当任务应用多实例标记时

“属性面板”指南

• 操作：选择任务的运行方式（Integration Service 操作、智能体操作或“无”用于建模）。
• 输入：为每次迭代提供值。
  示例：
  • 输入：invoiceId
  • Value: vars.invoiceList[index].id
• 输出：Maestro 会自动聚合所有输出。
• 更新变量：选择在每次迭代后或子流程完成后更新的内容。

iterator[0].item — 在从多实例任务调用的子流程中工作时

“属性面板”指南

• 操作：配置子流程与外部系统、API 或智能体交互的方式。
• 输入：映射当前元素或其属性。

示例：

• 输入：currentItemId
• Value: vars.itemsToProcess[index].id

示例：使用多实例执行验证发票列表

此示例显示如何配置服务任务，以在每个发票上运行一次。

1. 准备一个列表变量

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

2. 添加服务任务

1. 添加“服务”任务并将其命名为“验证发票”。
2. 打开“属性”面板，展开“多实例”。
3. 在“项目”中，选择 invoiceList。

3. 在输入中使用当前项目

在“输入”部分中：

• 示例：将 InvoiceId 设置为 vars.invoiceList[index]。
• 如果列表包含对象：
  使用 vars.invoiceList[index].Id。

4. 配置实施

在“实施”部分中：

• 操作： 启动并等待智能体
• 智能体：您的发票验证智能体

5. 调试流程

1. 选择“分步调试”。
2. 您将看到每个列表项目执行一次“验证发票”。
3. “执行”追踪记录会分别显示每个项目的运行情况。

并行多实例示例

1. 添加名为“验证发票”的服务任务。
2. 选择“更改元素”→ 选择“并行多实例”。
3. 在“属性”面板中，展开“多实例”。
4. 在“项目”中，选择列表变量（例如变量）。
5. 调试流程，以便在执行历史记录中查看每个列表元素的一个活动实例。

循环支持

使用多实例来替换手动循环。 将集合视为循环边界。 顺序模式按顺序处理项目，等待每个项目完成，然后再开始Processes。并行模式一次启动多个项目，完成所有项目或满足停止条件时结束。保持每个项目的工作幂等且持续时间短。如果您需要单个组合输出，请使用聚合。

视为可循环的集合类型

对于多实例执行，Maestro 将以下集合类型视为可循环：

• 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[]

运行时行为

1. 扇出 / 扇入：Maestro 为每个项目创建一个活动实例，在所有实例完成时（如果您在下游使用自定义停止策略，则更早）完成组。
2. 排序：在“顺序”模式下保证；在“并行”模式下不保证。
3. 并发：并行模式会并发运行项目，受平台限制和资源可用性的约束。
4. 失败：独立处理每个项目的结果。 下游逻辑应定义如何处理部分失败（例如，根据阈值继续、重试或停止）。
5. 可观察性：跟踪每次项目运行，启用每个项目状态和聚合结果。

示例

场景：您从外部 API 收到发票 ID 的列表，必须通过第二个 API 验证每个发票。

计划：

1. 获取发票 ID 的动态列表（从上一个步骤或外部查询中获取）。

2. 将“并行多实例标记”应用于验证活动，以在每个发票上散出一个操作。

3. 使用“聚合”为下游步骤生成单个组合输出（例如，{invoiceId, isValid, errors} 列表）。

   

最佳实践

1. 在“分配”之前验证集合（空或过大的列表）。
2. 保持每个项目的工作时间短且具有容错功能；在适当的情况下添加重试。
3. 仅聚合您需要的内容。 大型聚合会影响性能和可读性。
4. 将 Success 标准明确（例如）。

备注：

目前，并行多实例按 50 个批次执行元素。

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

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