service-omni-routing-flow-deploy

service-omni-routing-flow-deploy

Voice 运行时验证依赖已配置的 Contact Center。即使已部署的配置没有变化，Flow 重新部署也会报告 Changed。

通过 Metadata API 部署 Omni-Channel 路由 Flow，确认其状态为 Active，并证明它能够路由工作项——可通过 CLI 调用（自动启动的试运行），也可观察实际路由产生的副作用（记录触发型变体）。service-omni-channel-setup-coordinate 会在 service-omni-queue-deploy 创建目标队列并绑定其成员后接入该 Flow。

变体

assets/force-app/main/default/flows/ 下提供四个资源文件——Case 和 VoiceCall 各有一个自动启动型变体和一个记录触发型变体。使用 --target Case|VoiceCall（默认值为 Case）和 --trigger 选择变体。

变体	形态	验证内容	会路由实际工作项吗？
Omni_Route_Cases / Omni_Route_VoiceCalls（默认）	自动启动型，带 dryRun 门控	可通过 Actions REST 从 CLI 调用，不产生副作用	否
Omni_Route_Case_Trigger / Omni_Route_VoiceCall_Trigger（--trigger）	插入时触发的记录触发型 Flow，调用 routeWork	实际路由——插入记录会创建 PendingServiceRouting/AgentWork	是

自动启动型变体可低成本降低无头 CLI 路径的风险；记录触发型变体可证明实际记录会进入队列。完整的端到端流程会部署记录触发型变体。

使用 --trigger --routing-type SkillsBased 时，记录触发型变体取自同级的 <FlowDN>.SkillsBased.flow-meta.xml 资源文件，它会发出 routingType=SkillsBased 以及非空的 skillOption。基础触发型 Flow 将 routingType=QueueBased 写死，因此启用基于技能的路由配置的组织在运行时不会生效——此变体可确保其按技能路由（W-24069467）。

输入

bash scripts/deploy-and-report.sh <org-alias> [flow_developer_name] [--target Case|VoiceCall] [--trigger] [--routing-type QueueBased|SkillsBased] [--skill-option RunSBRRules|DefineSkillRequirements|Both] [--runtime-proof] [--require-proof] [--skip-invoke]
# autolaunched smoke test (Case):
bash scripts/deploy-and-report.sh myorg
# record-triggered Voice routing with runtime proof:
bash scripts/deploy-and-report.sh myorg --target VoiceCall --trigger --runtime-proof
# skills-based Case routing (platform evaluates WorkSkillRouting rules):
bash scripts/deploy-and-report.sh myorg --target Case --trigger --routing-type SkillsBased --runtime-proof

• --target Case|VoiceCall（默认值为 Case）——选择 Flow 对。
• --trigger——部署带动态令牌解析的记录触发型变体。
• --routing-type QueueBased|SkillsBased（默认值为 QueueBased；环境变量 OMNI_ROUTING_TYPE）——SkillsBased 会部署 <FlowDN>.SkillsBased 变体，该变体调用 routeWork 并传入 routingType=SkillsBased，使组织的基于技能的路由配置在运行时生效，而非处于未启用状态。它使用相同的 DeveloperName 部署，替换 QueueBased 触发型 Flow（同一对象上不会同时存在两个触发器）。
• --skill-option RunSBRRules|DefineSkillRequirements|Both（默认值为 RunSBRRules；环境变量 OMNI_SKILL_OPTION；仅适用于 SkillsBased）——RunSBRRules/Both 会让平台在服务端评估组织的 WorkSkillRouting 规则，并将匹配的 SkillRequirement 行附加到 PSR；DefineSkillRequirements 仅使用 Flow 自身传入的技能。若 SkillsBased 部署的 skillOption 为空或无效，则拒绝部署（退出码 2）：skillOption 为空会导致平台的 routeWork 操作发生 NPE，并回滚触发插入的记录（W-24069761），因此资源文件始终会携带非空值。
• --runtime-proof（隐含 --trigger）——部署后插入一条目标记录。QueueBased 接受 PendingServiceRouting 或 AgentWork 行。SkillsBased 要求存在至少包含一个 SkillRequirement 的 PendingServiceRouting，以证明 RunSBRRules 已评估生效的 WorkSkillRouting 规则。除非设为必需，否则验证失败时会软失败。之后始终会删除该记录。
• --require-proof（隐含 --runtime-proof；也可设置 OMNI_RUNTIME_PROOF_REQUIRED=1）——将该验证设为阻断项；这是 Voice 端到端流程的发布门禁。
• --skip-invoke（仅适用于自动启动型）——部署并验证 Active，不调用 Actions REST。
• 令牌覆盖（--trigger）：QUEUE_DEVELOPER_NAME、ROUTING_CONFIG_DEVELOPER_NAME、SERVICE_CHANNEL_DEVELOPER_NAME。协调器始终会使用为目标创建的资源提供这三个值，因此 Flow 会绑定到相同的渠道、队列和 QRC，而不是猜测默认值。

前提条件和安全

• 目标组织已通过 sf CLI 进行身份验证，拥有 Service Cloud 许可证，sf CLI ≥ 2.139.6，jq ≥ 1.6。
• 已启用 Omni-Channel 基本设置（service-omni-base-settings-configure）——仅当 Omni 已启用时，路由操作才能解析；没有该设置时，流可以部署，但在运行时会失败。
• 记录触发的运行需要已部署的 ServiceChannel（service-omni-service-channel-configure）、Queue（service-omni-queue-deploy）和 QueueRoutingConfig（service-omni-queue-routing-config-deploy），以解析其令牌化 ID；运行时验证还需要有一个具有兼容在线状态的在线 Agent（service-omni-presence-status-deploy）。
• 适用三项条件组成的 safe_to_write 生产环境防护机制。

运行

deploy-and-report.sh 会部署、验证，并按变体验证路由：

1. 解析令牌（仅记录触发型）——已提交的资产包含 __QUEUE_ID__、__ROUTING_CONFIG_ID__、__SERVICE_CHANNEL_ID__ 以及通道名称/标签令牌。该技能会按 DeveloperName 解析每个令牌，并写入一个不会提交的实体化副本（资产仍保留令牌，以便移植）。若无法解析 ServiceChannel，则会安全失败，而不会嵌入空 ID。
2. 部署——sf project deploy start --metadata "Flow:<FlowDN>"；files[].state 对应 reused／updated／created。
3. 验证 Active 状态——检索 Flow 并确认其资源 ID、routingType 和 SkillsBased skillOption 仍然匹配；否则重新部署。确认存在活动版本。
4. 验证路由——自动启动型：向 /actions/custom/flow/<FlowDN> 发送 POST 请求，内容为 {"dryRun":true}，并断言 isSuccess 和 dryRunOk。记录触发型：插入目标记录并观察路由情况。SkillsBased 成功还要求 PSR 上有一条或多条 SkillRequirement 记录。

行为

两种形态，两种验证路径。“能否无界面调用路由流？”和“真实记录是否会路由到队列？”是两个不同的问题。自动启动型 dryRun 流通过一次无副作用的 HTTP 调用回答第一个问题——该流必须有一条无需前置条件即可成功的代码路径，因此 dryRun=true 会执行一个赋值步骤并返回 dryRunOk=true。记录触发型流不会作为自定义操作公开，因此唯一的无界面验证方式是插入源记录并观察 PendingServiceRouting／AgentWork。PSR 记录本身只能证明流已完成路由；Agent 分配取决于 Omni 分发，而非流。

**活动版本往返验证。**对于记录触发型变体，组件部署状态只能证明事务已完成，不能证明存在活动版本。该技能优先使用 FlowDefinitionView.ActiveVersionId，若该视图不可用，则回退到活动 Tooling Flow 记录。若两个来源都无法证明存在活动版本，则会安全失败，因此没有证据时绝不会报告 flow_active:true。

绑定漂移时重新部署。reused 表示活动版本已存在，且其中嵌入的队列／QRC／ServiceChannel ID、路由类型和 SkillsBased 技能选项均与请求匹配。如果绑定或路由模式发生漂移，该技能会重新部署，而非复用。OMNI_FLOW_FORCE=1 会强制重新部署。

**幂等性注意事项。**与大多数元数据类型不同，Flow 部署并非按字节幂等——即使内容相同，Salesforce 也会在重新部署时报告 Changed，因为每次部署都可能增加一个版本。请将该技能返回的 updated 理解为“已成功重新部署”，而非“操作员修改了流”。

**安全。**部署使用显式的 --metadata "Flow:<DN>"（绝不使用 --source-dir），因此不会影响同级流；该技能也绝不会覆盖其未创建的 Flow——协调器会有意提供 flow_developer_name。由于该值会被插入 Actions REST URL 路径，因此会根据 ^[A-Za-z][A-Za-z0-9_]{0,79}$ 对 flow_developer_name 进行验证。

输出约定

单个 JSON 对象，包含 status（值为 created、reused、updated 或 blocked）、flow_developer_name、flow_state、flow_active、deploy_id、manual_actions 和 blocking_issue。自动启动变体还会添加 verification_path 和 invocation_smoke_test（attempted、success、endpoint、dry_run_ok）。记录触发变体还会添加 mode: "record_triggered"、target、flow_active_version_id、routing_type、skill_option（使用 SkillsBased 时的 skillOption，否则为 null）、resolved（queue/routing_config/service_channel）和 runtime_proof（attempted、required、success、record_id、pending_service_routing、agent_work、reason）。在 --routing-type SkillsBased 下，runtime_proof 还会包含 skill_requirement_count 和 skill_requirements——平台附加到 PSR 的 SkillRequirement 行（基于技能的验收信号）。

• blocked——部署失败；Flow 未处于 Active 状态；自动启动调用失败；无法解析队列/QRC；无法解析 ServiceChannel；或设置了 --require-proof，但未观察到对应模式的证明。对于 SkillsBased，PSR 中没有任何 SkillRequirement 行不算通过证明。普通的 --runtime-proof 失败仍按软失败处理。
• 除非传入 --runtime-proof/--require-proof，否则 runtime_proof.attempted 为 false；临时记录始终会被清理。

限制

• 仅支持 Case 和 VoiceCall；如需扩展，请派生最接近的资产，并保留 dryRun/dryRunOk 约定（自动启动），或 routeWork + 令牌化 ID 模式（记录触发）。
• 不会将 Flow 注册到队列的路由配置中——该绑定由 service-omni-queue-routing-config-deploy 负责。
• 不处理屏幕 Flow、平台事件触发的 Flow 或 Flow Tests。

参考资料

文件	阅读时机
references/api-notes.md	部署或验证行为异常时——用于查看变体对比、令牌解析表、Flow 架构、Actions REST 响应结构和记录 DML 验证