service-omni-routing-flow-deploy

service-omni-routing-flow-deploy

音声ランタイムの実証には、プロビジョニング済みのコンタクトセンターが必要です。デプロイ済みの設定に変更がなくても、フローの再デプロイでは Changed と報告されます。

Metadata API を使用して Omni-Channel ルーティングフローをデプロイし、Active になったことを確認して、作業をルーティングすることを実証します。方法は、CLI からの呼び出し（自動起動型のドライラン）か、実際のルーティングによる副作用の確認（レコードトリガー型）です。service-omni-channel-setup-coordinate は、service-omni-queue-deploy による対象キューの作成とメンバーの割り当てが完了した後に、このフローを組み込みます。

バリアント

assets/force-app/main/default/flows/ には 4 つのアセットが含まれています。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）	挿入時にトリガーされ、routeWork を呼び出すレコードトリガー型	実際のルーティング。挿入によって PendingServiceRouting / AgentWork が作成されます	はい

自動起動型は、ヘッドレス CLI の経路のリスクを低コストで低減します。レコードトリガー型は、実際のレコードがキューに到達することを実証します。フルのスチールスレッドでは、レコードトリガー型をデプロイします。

--trigger --routing-type SkillsBased を指定すると、レコードトリガー型は、routingType=SkillsBased と null ではない skillOption を出力する兄弟アセット <FlowDN>.SkillsBased.flow-meta.xml から取得されます。基本のトリガーフローでは 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）— フローのペアを選択します。
• --trigger — 動的トークン解決を使用して、レコードトリガー型のバリアントをデプロイします。
• --routing-type QueueBased|SkillsBased（デフォルトは QueueBased、環境変数 OMNI_ROUTING_TYPE）— SkillsBased を指定すると、routingType=SkillsBased で routeWork を呼び出す <FlowDN>.SkillsBased バリアントがデプロイされ、組織のスキルベースルーティング設定が無効なままではなく、実行時に反映されます。同じ DeveloperName でデプロイされ、QueueBased のトリガーを置き換えます（1 つのオブジェクトに 2 つのトリガーを設定することはありません）。
• --skill-option RunSBRRules|DefineSkillRequirements|Both（デフォルトは RunSBRRules、環境変数 OMNI_SKILL_OPTION、SkillsBased のみ）— RunSBRRules / Both は、プラットフォームに組織の WorkSkillRouting ルールをサーバー側で評価させ、一致した SkillRequirement 行を PSR に追加します。DefineSkillRequirements は、フロー自体が渡すスキルのみを使用します。空または無効な skillOption を指定した SkillsBased デプロイは拒否されます（終了コード 2）。skillOption が null の場合、プラットフォームの routeWork アクションで NPE が発生し、トリガーとなった挿入がロールバックされるためです（W-24069761）。そのため、アセットには常に null ではない値が設定されています。
• --runtime-proof（--trigger を含意）— デプロイ後、対象レコードを挿入します。QueueBased では PendingServiceRouting 行または AgentWork 行を受け付けます。SkillsBased では、アクティブな WorkSkillRouting ルールが評価されたことを実証するため、少なくとも 1 つの SkillRequirement を持つ PendingServiceRouting が必要です。必須でない場合、実証に失敗しても処理は続行されます。レコードは必ず後で削除されます。
• --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。コーディネーターは、対象用に確立したリソースから常にこの 3 つを指定します。これにより、推測したデフォルト値ではなく、同じチャネル、キュー、QRC にフローがバインドされます。

前提条件と安全性

• 対象組織は sf CLI で認証済みであり、Service Cloud ライセンス、sf CLI ≥ 2.139.6、jq ≥ 1.6 が必要です。
• Omni-Channel の基本設定を有効にします（service-omni-base-settings-configure）。Omni が有効な場合にのみルーティングアクションが解決されます。有効でなくてもフローはデプロイされますが、実行時に失敗します。
• レコード起動型フローを実行するには、トークン化された ID を解決するために、デプロイ済みの ServiceChannel（service-omni-service-channel-configure）、Queue（service-omni-queue-deploy）、QueueRoutingConfig（service-omni-queue-routing-config-deploy）が必要です。さらに、実行時の検証には、互換性のあるプレゼンスステータスでオンラインのエージェントが必要です（service-omni-presence-status-deploy）。
• 3 要素の 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. 有効状態を検証 — Flow を取得し、そのリソース ID、routingType、SkillsBased の skillOption が引き続き一致することを確認します。一致しない場合は再デプロイします。有効なバージョンが存在することも確認します。
4. ルーティングを実証 — 自動起動型：{"dryRun":true} を指定して /actions/custom/flow/<FlowDN> に POST し、isSuccess と dryRunOk を検証します。レコード起動型：対象レコードを挿入し、ルーティングを確認します。SkillsBased の成功には、PSR 上の SkillRequirement 行が 1 つ以上必要です。

動作

2 つの形式と 2 つの検証経路。 「ルーティングフローをヘッドレスで呼び出せるか」と「実際のレコードがキューにルーティングされるか」は別の問いです。自動起動型の dryRun フローは、副作用のない 1 回の HTTP 呼び出しで前者に回答します。フローには前提条件なしで成功するコードパスが必要なため、dryRun=true の場合は割り当てステップを実行し、dryRunOk=true を返します。レコード起動型フローはカスタムアクションとして公開されないため、ヘッドレスで実証する唯一の方法は、ソースレコードを挿入して PendingServiceRouting／AgentWork を確認することです。PSR 行だけでフローによるルーティングは証明できます。エージェントの割り当てはフローではなく、Omni の配布に依存します。

有効バージョンのラウンドトリップ。 レコード起動型バリアントでは、コンポーネントのデプロイ状態が証明するのはトランザクションのみで、有効なバージョンの存在は証明しません。スキルは FlowDefinitionView.ActiveVersionId を優先し、そのビューを利用できない場合は、Tooling API の 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 を指定します。flow_developer_name は Actions REST URL のパスに埋め込まれるため、^[A-Za-z][A-Za-z0-9_]{0,79}$ に照らして検証されます。

出力契約

status が created | reused | updated | blocked のいずれかで、flow_developer_name、flow_state、flow_active、deploy_id、manual_actions、blocking_issue を含む単一の JSON オブジェクトです。自動起動型のバリアントでは、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 — デプロイに失敗した、フローが Active ではない、自動起動の呼び出しに失敗した、キュー/QRC を解決できなかった、ServiceChannel を解決できなかった、または --require-proof が指定され、モード固有の証明が確認できなかった場合です。SkillsBased の場合、SkillRequirement 行が 0 件の PSR は証明として合格しません。通常の --runtime-proof の失敗は fail-soft のままです。
• runtime_proof.attempted は、--runtime-proof/--require-proof が渡されない限り false です。使い捨てレコードは常にクリーンアップされます。

制限事項

• Case と VoiceCall のみが対象です。最も近いアセットをフォークし、dryRun/dryRunOk の契約（自動起動型）または routeWork とトークン化 ID のパターン（レコードトリガー型）を維持して拡張してください。
• フローをキューのルーティング設定に登録しません。このバインディングは service-omni-queue-routing-config-deploy が担当します。
• 画面フロー、プラットフォームイベントトリガーフロー、Flow Tests には対応していません。

参考資料

ファイル	読むタイミング
references/api-notes.md	予期しないデプロイまたは検証動作が発生した場合 — バリアントの比較、トークン解決テーブル、フロースキーマ、Actions REST のレスポンス形式、レコード DML 検証