队列触发器

创建和管理队列触发器，包括时区和非工作日日历限制。

重要提示：

• 您可以为队列创建一个队列触发器。 这也适用于共享到多个文件夹的队列。
• 触发器时区：在触发器上设置的时区不受租户时区的限制。但是，如果您使用非工作日日历，则无法设置不同的时区。 队列触发器根据在触发器级别定义的时区启动。 队列触发器会基于队列项目处理而启动。 基于触发器时区禁用队列触发器。

队列触发器在创建触发器后或将新项目添加到队列中时立即启动流程。触发器在与所选流程关联的环境中运行。

当在短时间内添加大量队列项目时（例如，使用 AddQueueItem 或 BulkAddQueueItems），流程可能不会立即启动。 为了处理此类情况，我们实施了重新检查机制，以确保在资源可用后触发流程。

重要提示：

队列触发器的实现针对使用具有内部循环的流程进行了优化，以便在退出之前处理所有可用的队列项目。如果流程不实施此策略，则不会产生最佳体验，并且可能无法满足所需的业务要求。

以下这些选项可帮助您参数化流程触发的规则：

	描述
触发第一个作业的最小项目数	项目处理作业仅在目标队列中具有至少此数量的新项目之后才开始。延迟的队列项目不计算在内。
允许同时等待和运行的最大作业数	允许的待处理作业和正在运行的作业的最大数量（一起计算）。对于同时允许的 2 个或多个作业，需要按如下所述定义第三个选项。
每 __ 个新项目触发另一个作业。	触发新作业的新项目的数量（在为第一个选项定义的项目数的基础上增加）。 仅在允许同时两个或更多作业（使用上述选项定义）时启用。
完成作业后，重新评估条件，并在可能的情况下开始新作业	如果选中，则会在每个作业完成后评估队列触发器，并在机器人可用时启动新作业。这是对每 30 分钟一次的自动检查的补充，并有助于确保尽可能以无延迟的方式处理剩余队列项目。

为了处理在加入队列时无法处理的队列项目（包括重试项目），默认情况下每 30 分钟执行一次未处理项目检查，如果满足触发条件，则会再次启动触发器。

您可以使用“队列 - 未处理队列项目检查频率（分钟）”参数来调整默认的 30 分钟检查间隔。

此检查可确保在以下情况下队列中的所有项目都能得到处理：

• 队列项目添加到队列的速度比使用可用资源处理队列项目的速度要快得多。
• 队列项目是在非工作日添加到队列中的，但是只能在工作时间进行处理。
• 队列项目处理将推迟到以后的时间。经过这段时间后，一旦经过 30 分钟的检查确定，便可以对其进行处理。
  备注：

  默认检查时间为 30 分钟，因此在非工作时间存在资源阻塞的风险。为避免这种情况，请确保在工作日结束时没有未处理的项目。如果不可能，请确保触发的流程不需要人工干预。

队列触发器处理算法

变量

变量	描述
newItems	队列中可用的新队列项目数。
minItemsToTrigger	触发第一个作业所需的最小项目数。仅当新项目数至少达到此数量时，才会启动第一项作业。
maxConcurrentJobs	允许同时等待和运行的最大作业数。这是并行作业的上限。
itemsPerJob	触发每个后续作业所需的额外项目数。达到 minItemsToTrigger 后，启动一个作业。超过 minItemsToTrigger 项后，每增加 itemsPerJob 项，就会多启动一个作业（最多 maxConcurrentJobs 个）。
pendingJobs	当前处于待处理状态的作业数。
runningJobs	处于已恢复、运行中、正在停止或正在终止状态的作业数。
enablePendingJobsStrategy	Boolean 设置，用于确定运行中的作业是否会计入剩余容量。

触发器 - 队列触发器 - 启用待处理作业策略设置决定了 Orchestrator 如何计算剩余容量，即允许其调度的额外作业数量：

• True – 剩余容量 = maxConcurrentJobs减去pendingJobs 。当正在运行的作业预计已从“新”状态声明其队列项目时，请使用此设置。
• False – 剩余容量 = maxConcurrentJobs 减去 pendingJobs 减去 runningJobs。预计运行中的作业尚未从新建状态领取其队列项目时，请使用此设置。

Orchestrator 会调度两者中较小的那个值：剩余容量，或根据队列项目数量计算出的所需作业数。因此，该设置控制着新作业调度工作的保守程度或积极程度。

公式

1. 剩余容量

if enablePendingJobsStrategy = true:
    remainingCapacity = maxConcurrentJobs - pendingJobs

if enablePendingJobsStrategy = false:
    remainingCapacity = maxConcurrentJobs - pendingJobs - runningJobs

2. 所需作业（未考虑容量限制之前）

if newItems < minItemsToTrigger:
    desiredJobs = 0
else:
    desiredJobs = 1 + (newItems - minItemsToTrigger) / itemsPerJob   [integer division]

3. 要调度的作业

jobsToSchedule = min(desiredJobs, remainingCapacity)

重要提示

• 每当添加单个队列项目（包括通过批量添加）时，都会发生此评估。
• 为确保将已推迟（延迟）的队列项目考虑在内，每个队列触发器都有一个关联的计划，该计划将重新检查上述整个算法。默认情况下，此操作每 30 分钟进行一次，但可以通过“队列 - 未处理的队列项目检查频率（分钟）”租户设置将其减少到至少 10 分钟。
  备注：

  只有在其推迟时间过后，才会处理推迟的项目。用于检查推迟项目的内置作业每 30 分钟运行一次。但是，如果在推迟的项目已经可用后将新项目添加到同一队列中，则将立即重新触发队列触发器，并且可以选取推迟的项目，而无需等待下一次计划的检查。

• 该算法旨在确保作业在达到阈值后立即启动，并且在超过阈值时，其他作业将启动，以帮助处理增加的积压。其目的不是在计算机之间均匀分配工作负载，而是确保存在足够的作业。
• 启动的作业与其处理的队列项目之间没有硬链接。作业 J 未必分配给队列项目 a、b 或 c。
• 根据是批量添加还是单独添加队列项目，算法结果会有所不同，因为这会影响所执行的评估次数。
• 使用队列触发器时，您可能会遇到以下警示：The trigger could not create a job as the maximum number of jobs has been reached. 此警示仅供参考，通常意味着当 Orchestrator 尝试启动一个作业时，另一个作业已在运行。如果您对当前的作业能力感到满意，可以放心将其忽略。

示例

场景 1 - 单独添加的队列项目

对于此场景， “启用待处理作业”策略参数（键值对）设置为False 。有关如何更新值的更多信息，请参见“租户设置” 。

此场景中使用了两个作业：

• 其中一个在 20 秒内每秒向目标队列添加 3 个项目（共 60 个项目）。
• 每秒可处理目标队列中的 1 个项目。

触发器配置如下：

• 触发第一个作业的最小项目数： 31
• 允许同时等待和运行的最大作业数： 3
• 为每个新项目触发了另一个作业: 10新项目

将项目添加到队列的作业开始后：

1. 11 秒（33 个项目）后，将触发第一个项目处理作业。
2. 再过 4 秒（12 个项目）后，将触发第二个项目处理作业。
3. 再过 4 秒（12 个项目）后，系统将触发第三个项目处理作业。

直到结束添加队列项目时，第一个作业已处理 9 个项目，第二个处理 5 个项目，第三个处理 1 个项目——三个作业在 20 秒内处理了 15 个项目。

剩余 45 个项目 (60 − 15) 将由 3 个作业处理，每秒处理 1 个项目，再需要 15 秒即可完成。总处理时间：35 秒。

场景 2 - 批量添加队列项目

对于此场景， “启用待处理作业”策略参数（键值对）设置为False 。有关如何更新值的更多信息，请参见“租户设置” 。

如果使用一次批量操作（没有运行或待处理的作业）添加场景 1 中的 60 个队列项目，将创建 3 个作业。

如果至少一个作业在重新评估计划之前完成，则系统会进一步创建更多作业。

启用待处理作业策略示例

以下示例显示了启用待处理作业策略设置在启用后可能会导致过度调度，在禁用后可能会导致调度不足。

触发器配置

设置	值
触发所需的最少队列项目	1
待处理和运行中的作业数上限	1,000
为每个项目触发了其他作业	1 个新项目
完成作业后，重新评估	True
启用待处理作业策略	True（第 1 部分）

假设：作业需要 30 秒时间将队列项目移出新建状态。

第 1 部分：启用“启用待处理作业策略”时过度调度

步骤 1：将 1,100 个项目批量添加到队列，触发 1,000 个作业。

步骤 2：仅有 200 个机器人可用。200 个作业正在运行，800 个作业仍在等待处理。

作业	计数
正在运行	200
待处理	800

队列项目	状态
200	处理中
900	新添加

步骤 3：200 个运行中的作业完成，触发另外 200 个作业的运行。

作业	计数
正在运行	200
待处理	600

队列项目	状态
200	成功
200	处理中
700	新添加

步骤 4：由于启用了完成作业后，重新评估，触发器会在几秒钟内再次运行。启用启用待处理作业策略后，Orchestrator 会假设所有 200 个运行中的作业均已将其队列项目移出新建状态，尽管这实际上需要 30 秒时间。

步骤 5：此时的触发器计算：

remainingCapacity = maxConcurrentJobs - pendingJobs = 1000 - 600 = 400
desiredJobs       = newItems - pendingJobs          = 700 - 600  = 100
jobsToSchedule    = min(100, 400)                               = 100

调度了另外 100 个作业。但是，由于 200 个运行中的作业尚未将其项目移出新建状态（需要 30 秒），因此在只有约 500 个真正需要新作业的情况下，Orchestrator 会将 700 个新建项目视为未覆盖。结果会出现大约 100 个过度调度的作业。

备注：

Orchestrator 不会跟踪个别作业和个别队列项目之间的关系，因此无法自行检测过度调度。识别过度调度需要外部状态跟踪。

步骤 6：禁用启用待处理作业策略后，相同情况会导致：

remainingCapacity = maxConcurrentJobs - pendingJobs - runningJobs = 1000 - 600 - 200 = 200
desiredJobs       = newItems - pendingJobs - runningJobs           = 700 - 600 - 200 = -100 → 0
jobsToSchedule    = min(0, 200)                                                      = 0

未调度其他作业，在此场景中，这更接近于正确结果。

第 2 部分：已禁用“启用待处理作业策略”的调度不足（已禁用）

步骤 1：在此场景中，作业不会同时完成。在最初 200 个作业中，100 个作业在 60 秒后完成，另外 100 个作业在 90 秒后完成。

步骤 2：完成前 100 个作业，触发另外 100 个作业。

作业	计数
正在运行	200
待处理	700

队列项目	状态
100	成功
200	处理中
700	新添加

步骤 3：由于启用了完成作业后，重新评估，触发器会在几秒钟内再次运行。

步骤 4：启用“启用待处理作业策略”时：

remainingCapacity = maxConcurrentJobs - pendingJobs          = 1000 - 700 = 300
desiredJobs       = newItems - pendingJobs                   = 700 - 700  = 0
jobsToSchedule    = min(0, 300)                                           = 0

未调度其他作业。这是正确的，即 700 个新建项目对应 700 个待处理作业。

步骤 5：禁用启用待处理作业策略后：

remainingCapacity = maxConcurrentJobs - pendingJobs - runningJobs = 1000 - 700 - 200 = 100
desiredJobs       = newItems - pendingJobs - runningJobs           = 700 - 700 - 200 = -200 → 0
jobsToSchedule    = min(0, 100)                                                       = 0

此处也未调度其他作业。但是，如果待处理作业数量减少，该公式将导致调度不足：它会假设运行中的 200 个作业尚未从新建状态中领取项目，尽管其中 100 个作业已领取。

步骤 6：由于调度不足而未调度的作业最终会在未处理的队列项目检查按计划运行时被提取。这就是检查的目的。

摘要

设置	关于运行中作业的假设	结果
已启用 (true)	已声明其队列项目	可能会过度调度
已禁用 (false)	尚未领取其队列项目	可能会调度不足（通过定期重新检查来缓解）

Queue triggers with Maestro processes

Queue triggers can start Maestro processes (BPMN, Flow, and Case Management types) when new items are added to a queue. Unlike RPA processes, which can implement complex batching logic, Maestro queue triggers are configured with fixed constraints to enforce a one-to-one mapping between queue items and process instances.

Configuration constraints for Maestro

When creating a queue trigger for a Maestro process, the following fields are automatically locked to their required values and cannot be modified:

字段	值	原因
触发第一个作业的最小项目数	1	Each queue item triggers exactly one process instance
每 __ 个新项目触发另一个作业。	1	Ensures one-to-one mapping between items and process instances

These constraints ensure that each queue item is processed by exactly one Maestro process instance. Unlike RPA processes, each Maestro instance handles one queue item at a time and delegate item lifecycle management to Maestro's queue operation tasks.

Queue item lifecycle with Maestro

When a Maestro process is triggered by a queue item, the item transitions through the following statuses:

• New: item is added to the queue and awaiting processing
• In Progress: Maestro process has started execution
• Successful or Failed: Maestro process has completed and set the final status

Maestro processes use dedicated queue activity tasks to manage queue items:

• Delete queue items
• Bulk add queue items
• Set transaction status (Successful/Failed)
• Set transaction progress
• Postpone transaction items

备注：

If you have existing queue triggers configured for RPA processes with different batching rules, those configurations remain unchanged. Queue trigger constraints only apply when the triggered process is a Maestro process.

执行目标

您可以配置多个规则，具体取决于执行哪些关联的流程。

描述
帐户	The process is executed under a specific account. Specifying only the account results in Orchestrator allocating the machine dynamically. Specifying both the account and the machine template means the job launches on that very account-machine pair.
计算机	The process is executed on one of the host machines attached to the selected machine template. Specifying only the machine template results in Orchestrator allocating the account dynamically. Specifying both the account and the machine template means the job launches on that very account-machine pair. 注意：确保将执行作业所需的运行时许可证分配给关联的计算机模板。
主机名	主机名 选择计算机模板后，系统将显示“主机名”选项，允许您选择所需的工作站/机器人会话以执行流程。 系统将显示活动文件夹中的所有可用会话，包括未连接、已断开连接或已连接的会话。 注意：确保将执行作业所需的运行时许可证分配给关联的计算机模板。

使用 UiPath 活动创建的队列触发器

RPA Developer 也可以在 Studio 的设计时中使用 UiPath.Core.Activities 包的“将新项目添加到队列时”活动创建队列触发器。

Orchestrator 将这些类型的触发器标识为包要求，通过“包要求”页面完成相关操作是在 Orchestrator 中添加这些触发器的唯一方法。

在设计时设置的任何配置都会反映在 Orchestrator 中，并且无法修改。

例如：将队列项目添加到队列时，我希望以日志消息的形式接收其元数据。此处的区别在于，队列触发器指示自动化从工作流内部开始，而 Orchestrator 队列触发器指示自动化从工作流外部开始。