service-omni-channel-setup-coordinate

service-omni-channel-setup-coordinate

既存の状態を検出し、不足している要素のみを作成またはデプロイして、エージェント、キュー、プレゼンスステータス、権限を備えたルーティング環境を構築できるよう、組織を調整します。Case と VoiceCall には、ルーティングの完全な作成とバインド（キュー + QueueRoutingConfig + 送信ルーティングフロー）が用意されています。Incident と MessagingSession は、このコーディネーターによる 検証と既存設定の採用のみ を行います。状態を報告し、既存の設定を再利用しますが、不足しているキュー／QRC／フローは作成しません。MessagingSession のハンドオフを作成してバインドするには、service-agentforce-human-escalation-configure を使用してください。これはコーディネーターであり、正規の一連の手順に従って子のリーフスキルを順番に実行します。自身では書き込みを行いません。各リーフは1つのプリミティブを担当します。コーディネーターは組織ごとの ID を解決し、リーフ間で受け渡すとともに、共通の再利用／作成および安全性に関する契約を適用します。オペレーターが操作する必要のある前提条件（機能ライセンスがない場合、または対象の sObject が有効になっていない場合）に限り、クリックパスを示して処理を中断します。

python3 が記載されているのは、同梱の契約テスト（scripts/tests/test_omni_contracts.py）で使用するためだけです。コーディネーターの実行に必要なのは jq と sf のみです。

Inputs

書き込みを行う前に、最初に一度だけ以下を確認してください。

• エージェント数（デフォルトは 3、範囲は 1..10）とスーパーバイザー数（デフォルトは 1、範囲は 1..5）。
• 実際のログイン用メールアドレス（パスワードリセットのフローで使用します）。
• routing_targets（デフォルトは ["Case"]）— Case | Incident | MessagingSession | VoiceCall の任意のサブセットです。完全な作成キュー＋QRC＋ルーティングフローが設定されるのは Case と VoiceCall のみです。Incident と MessagingSession は検証され、既存のものが採用されます（レポートのみ）。
• サービスチャネルの戦略 — 標準のチャネル（Cases、sfdc_livemessage、デフォルト）を再利用するか、カスタムチャネルを作成します。
• エージェント／スーパーバイザーのプロファイル — ドライバーはデフォルトで Service Cloud User プロファイルのユーザーをプロビジョニングします（Omni には Service Cloud ライセンスが必要です）。組織によっては、そのライセンスが別の名前のプロファイル（例：Service Cloud）に付与されている場合があります。スクリプトを編集せずに OMNI_AGENT_PROFILE / OMNI_SUPERVISOR_PROFILE で上書きできます。指定したプロファイルが存在しない場合、ユーザー作成リーフは処理を中断します。
• ランタイムの証明（任意）— OMNI_RUNTIME_PROOF=1 にすると、ルーティングフローリーフでトリガーが実行されます（失敗しても処理は継続します）。OMNI_RUNTIME_PROOF_REQUIRED=1 にすると、証明が必須になります。QueueBased の証明には PendingServiceRouting または AgentWork が必要です。SkillsBased の証明には、少なくとも 1 つの SkillRequirement を持つ PendingServiceRouting が必要です。これは WorkSkillRouting が実際に実行されたことを示す受け入れシグナルです。使い捨てレコードは必ずクリーンアップされます。
• キューの選択（任意）— 対象に特定の既存キューまたは標準キューを使用する必要がある場合は、OMNI_CASE_QUEUE_DEVELOPER_NAME、OMNI_VOICE_QUEUE_DEVELOPER_NAME、OMNI_INCIDENT_QUEUE_DEVELOPER_NAME、または OMNI_MESSAGING_QUEUE_DEVELOPER_NAME を設定します。上書きがない場合、各リーフは対象から決まるデフォルトを使用します。
• ルーティング設定の選択（任意）— 既存の QRC を明示的に選択するには、OMNI_CASE_ROUTING_CONFIG_DEVELOPER_NAME または OMNI_VOICE_ROUTING_CONFIG_DEVELOPER_NAME を設定します。キューのみが上書きされた場合、コーディネーターはまずそのキューにリンクされた QueueRoutingConfig.DeveloperName を採用します。標準の QRC を作成するのは、キューにリンクされた設定がない場合のみです。
• キューのルーティング制御（任意）— OMNI_QRC_PUSH_TIMEOUT はエージェントの応答タイムアウトを設定し、OMNI_QRC_CAPACITY_PERCENTAGE は容量の割合を選択します（たとえば、エージェントの全容量を消費する VoiceCall には 100 を指定します）。コーディネーターは両方の値をすべての QRC 対象に渡します。
• ルーティングモード — OMNI_ROUTING_TYPE=QueueBased|SkillsBased の設定は任意です。OMNI_WSR_ENTITY / OMNI_WSR_FIELD / OMNI_WSR_SKILL / OMNI_WSR_VALUE の 4 つすべてが指定されている場合、コーディネーターは SkillsBased と推定します。それ以外の場合は、デフォルトの QueueBased になります。SkillsBased では OMNI_SKILL_OPTION=RunSBRRules（デフォルト）を使用し、プロビジョニングされたエージェントを OMNI_SBR_SKILL（デフォルトは OMNI_WSR_SKILL）に関連付け、WorkSkillRouting ルールを作成してからフローを有効化します。マッピングが不完全な場合や、SBR と WSR のスキルが一致しない場合は、書き込みを行う前に拒否されます。OMNI_WSR_LABEL でルール名を指定することもできます。
• 担当者エクスペリエンスのステージ（任意、デフォルトではオフ）— OMNI_REP_EXPERIENCE=1 にすると、プレゼンスユーザー設定（辞退＋辞退理由＋ACW）と Omni サイドバーが追加されます。OMNI_CONSOLE_APP=<app DeveloperName> で特定のコンソールアプリを指定できます。空の場合は自動検出されます。
• スーパーバイザー画面（常に実行、設定の後）— OmniSupervisorConfig が存在すると、コーディネーターは Data API を使って標準のアクション＋タブ画面（OmniSupervisorConfigAction / OmniSupervisorConfigTab）を設定します。クラシック設定のデプロイ直前には、読み取り専用の Command Center 分析も実行し、組織がクラシック画面と Command Center V2 のどちらを使用しているかを報告します。
• スーパーバイザー設定の選択（任意）— OMNI_SUPERVISOR_CONFIG_DEVELOPER_NAME を設定すると、設定ステージと画面ステージの両方で調整対象となるクラシック OmniSupervisorConfig.DeveloperName を正確に指定できます。デフォルトは Omni_Supervisor です。組織に複数の設定がある場合は上書きしてください。コーディネーターが推測で選択することはありません。新しい選択済み設定を作成する場合は、OMNI_SUPERVISOR_CONFIG_MASTER_LABEL でラベルを指定できます。

plan モードまたは run モードで実行します。

bash scripts/integration-driver.sh --plan <org-alias> [agent_count] [routing_targets_csv] [supervisor_count]
bash scripts/integration-driver.sh --run  <org-alias> [agent_count] [routing_targets_csv] [supervisor_count]

--plan は完全な読み取り専用プレビューです。各リーフは独自の検出を実行し、reused、action_needed、blocked のいずれかを報告します。前提条件がまだ整っていないリーフは、調査せずに保留中の作業として報告されるため、順序が前の段階にあるだけのステップが、誤解を招く赤色で表示されることはありません。クリーンなプラン（すべて reused、終了コード 0）は、組織がすでに設定済みであることを意味します。黄色の項目（終了コード 2）があれば、作業が残っています。

前提条件と安全性

• My Domain URL（.lightning.force.com ではありません）を使用して、sf CLI で認証済みの組織に接続していること。
• エージェント数に対して十分な余裕がある Service Cloud ライセンス。
• Incident をターゲットにするには Incident Management 機能が有効である必要があります。MessagingSession には Enhanced Messaging、VoiceCall には Service Cloud Voice が必要です。要求されたターゲット sObject が存在しない場合、準備状況チェックはクリックパスを示してハードフェイルします。
• 本番環境のガードレール： IsSandbox = true、TrialExpirationDate != null、OrganizationType IN ('Developer Edition', 'Base Edition') のいずれかが成り立つ場合に限り、safe_to_write は true になります。false の場合、実行はハード拒否されます。CDO は IsSandbox=false かつ TrialExpirationDate が null ではない値を返し、許可する必要があるため、IsSandbox だけをガード条件にすることはできません。

準備状況チェック（無言で実行、必須、各リーフの実行前）：

1. sf org display → 組織のエイリアスが認証済みであることを確認します。未認証の場合は拒否します（終了コード 1）。
2. Organization（IsSandbox、TrialExpirationDate、OrganizationType）→ safe_to_write を計算します。false の場合は拒否します（終了コード 1）。
3. エンティティの事前確認 → 各 Case 以外のルーティングターゲットについて、EntityDefinition を使用して sObject が存在することを確認します。ターゲットが存在しない場合は、機能を有効にするクリックパスを示してハードフェイルします（終了コード 2）。Case は存在するものと見なし、確認をスキップします。

Omni-Channel の基本設定の有効化は、実行前の独立した確認項目ではありません。基本設定のリーフ（ステップ 1）で検出されます。後続の Omni-Channel 依存リーフは、有効になるまで --plan では保留中として先送りされます。ドライバーは、この準備状況チェックで UserLicense の余裕や ServicePresenceStatus／QueueRoutingConfig の利用可否を事前確認しません。

このコーディネーターが連携するスキル

コーディネーターは、書き込み処理をすべてリーフスキルに委譲します。sObject 固有のリーフ（3、5、6、6c、7）はルーティング対象ごとに1回実行し、それ以外は1回実行します。SkillsBased ルーティングでは、トリガーフローを有効化する前にステップ6aと6bを完了します。ステップ10a（command-center-analyze）は読み取り専用のアドバイザリーで、常に実行します。ステップ11a（supervisor-surface-deploy）は、スーパーバイザー設定の成功後に常に実行します。リーフ12～13は、オプトインの担当者エクスペリエンス段階です（OMNI_REP_EXPERIENCE=1）。

#	子スキル	役割
1	service-omni-base-settings-configure	Settings:OmniChannel（5個の切り替え設定）をデプロイする
2	service-omni-agent-users-create	要求されたエージェントユーザーをプロビジョニングする
3	service-omni-service-channel-configure	対象のsObjectに対応する標準のServiceChannelを再利用するか、正規のXMLをデプロイする
4	service-omni-queue-routing-config-deploy	対象のQueueRoutingConfig（例：Case_Routing_Config、Voice_Routing_Config）をアップサートする
5	service-omni-queue-deploy	対象のsObjectに関連付けられたQueueを検出するか作成（--create-if-missing）し、QRCに合わせる
6	service-omni-queue-members-assign	検出されたキューにユーザーを割り当てる
6a	service-omni-skills-based-routing-configure	(SkillsBasedのみ) Skillと、アクティブなエージェントのSkillUser関連付けが存在することを確認する
6b	service-omni-work-skill-routing-configure	(SkillsBasedのみ) フローを有効化する前に、必須のフィールド値からSkillへのルールを作成する
6c	service-omni-routing-flow-deploy	Case／VoiceCall用のレコードトリガー型QueueBasedまたはSkillsBasedのFlowをデプロイする。SkillsBasedではskillOption=RunSBRRulesを渡す
7	service-omni-presence-status-deploy	一致するチャネルに関連付けられたAvailable_<sObject>をデプロイし、共通のBusyステータスがあることを確認する
8	service-omni-permission-set-assign	エージェントユーザーにOmni_Agent PermissionSetを割り当てる。バンドルされたメタデータがない場合は自己修復する（実行モードのみ）
9	service-omni-supervisor-users-create	スーパーバイザーユーザーをプロビジョニングする
10	service-omni-supervisor-permset-assign	標準のContactCenterSupervisor PermissionSetをスーパーバイザーユーザーに割り当てる
10a	service-omni-command-center-analyze	読み取り専用のアドバイザリー — 組織が従来のスーパーバイザー画面とCommand Center V2のどちらを使用しているかを報告する。書き込みや実行のハードブロックは行わない
11	service-omni-supervisor-config-deploy	ステップ5で検出されたキューにスーパーバイザーユーザーを関連付けるOmniSupervisorConfigをデプロイする
11a	service-omni-supervisor-surface-deploy	ステップ11の設定にスーパーバイザーのアクション＋タブ画面（OmniSupervisorConfigAction／OmniSupervisorConfigTab）を設定する
12	service-omni-presence-user-config-deploy	(オプトイン) PresenceUserConfigとPresenceDeclineReason（辞退＋ACW）をデプロイし、プロビジョニング済みのエージェントを割り当てる
13	service-omni-sidebar-configure	(オプトイン) CustomApplication.isOmniPinnedViewEnabled=trueを設定して、コンソールアプリにOmniユーティリティ領域を固定表示する
—	platform-metadata-deploy	デプロイリーフが使用する基盤のMetadata APIデプロイ

動作

再利用と作成の契約（すべてのエンティティで適用）。 DeveloperName（または自然キー）で検索し、存在する場合は標準レコード（Cases、sfdc_livemessage）を再利用します。存在しない場合は、リーフにバンドルされた定義から作成します。同名のカスタムレコードが存在する場合は冪等に整合させます。標準レコードや管理対象レコードを重複作成、改名、または変更して、その識別情報を変えることは決してありません。

実行順序とゲーティング。 リーフは依存関係の順に実行されます。以下のすべての書き込みには、基本設定が必須の前提条件です。SkillsBased ルーティングでは、ルーティングフローリーフ（6c）でトリガーを有効化する前に、エージェントの SkillUser バインディング（6a）と WorkSkillRouting ルール（6b）が成功している必要があります。また、フローにはキュー（5）とそのメンバー（6）が必要であり、FlowDefinitionView.ActiveVersionId を往復してフローが有効（Active）であることを証明します。必要な実行時の証明は、PSR が存在するだけでは合格になりません。SkillsBased では、その PSR に少なくとも 1 つの SkillRequirement が必要です。

スーパーバイザーの経路。 スーパーバイザーユーザー（9）には、エージェントユーザーと同じ Anonymous Apex の System.setPassword モデルを使用します。デバッグ TraceFlag が有効な場合、パスワードのリテラルが ApexLog に記録される可能性があるため、両方のユーザー作成リーフは最初の System.setPassword より前にフェイルクローズします。SOQL で絞り込んだ Tooling API クエリ（ExpirationDate > now）によって実行ユーザーに有効な TraceFlag が存在しないことを証明し、それを確実に証明できない場合はパスワードを一切設定しません（ユーザーは ACTIVE のまま reset_required となり、security_warning が付与されます）。ログは削除しないため、無関係な監査ログには影響しません。スーパーバイザー権限セットのリーフ（10）では、標準の ContactCenterSupervisor を割り当てます。割り当てに失敗するライセンス制限付き権限を持つカスタムの Omni_Supervisor は割り当てません。この配線はコントラクトテストで検証されます。スーパーバイザー権限セットの後、読み取り専用の Command Center 分析（10a）で、組織のスーパーバイザー機能（従来型と Command Center V2 のどちらか）を報告します。書き込みは行わず、決してハードブロックしません（検出が曖昧な場合は黄色、問題なく読み取れた場合は緑色）。設定（11）が反映されたら、サーフェスリーフ（11a）が標準のアクションとタブのペア（OmniSupervisorConfigAction／OmniSupervisorConfigTab）を設定の Id に関連付けて挿入します。これは通常の Data API 行なので、メタデータファイルの再デプロイは不要です。また、未作成の種類だけを挿入するため冪等です。設定が成功した後にのみ実行されます。設定がスキップまたは失敗した場合、依存関係に関する注記を付けてサーフェスをスキップします。

任意の担当者エクスペリエンスの段階。 OMNI_REP_EXPERIENCE=1 の場合、Presence ユーザー設定（12）は、辞退理由を含むバリデーターに準拠した PresenceUserConfig をデプロイし、再利用したユーザーも含め、解決されたすべてのエージェントのユーザー名を割り当てます。サイドバー（13）は OMNI_CONSOLE_APP に Omni ユーティリティ領域を固定するか、コンソールアプリが 1 つだけの場合は自動検出します。SkillsBased ルーティングは見た目だけの担当者エクスペリエンス段階ではありません。要求された場合、フローの有効化前に SkillUser と WorkSkillRouting の前提条件が実行されます。

ログイン動作のギャップ。 ログイン動作のラジオボタン（Setup → Omni-Channel Settings →「エージェントが新しいウィンドウ／タブを開いたときのログイン動作を定義」）には、v66 の公開 API がありません。基本設定のデプロイ後、コーディネーターは正確なクリック手順を提示します。デプロイはされてもラジオボタンの動作を制御しない enableOmniAutoLoginPrompt による切り替えは試みません。references/gap-catalog.md を参照してください。

認証情報。 生成されたパスワードは、アクセス制限付きの単一の CREDENTIALS.json（モード 0600）に移され、他のすべての成果物からは伏せ字にされます。書き込みはアトミックで、フェイルクローズです。伏せ字処理または検証に失敗した場合、平文の成果物を削除して実行を中止するため、成果物ディレクトリに平文のパスワードは残りません。オペレーターは CREDENTIALS.json を一度だけ読み取り、安全な方法で配布してから削除します。

出力契約

成果物は単一のレポートファイルです。最後の操作として、必ず Write ツールを使用して、完全なレポートを現在の作業ディレクトリにある omni-coordinate-report.md に保存してください。チャットでのみ提供してはいけません。--run モードでは、実際に起きたこと（作成されたリソース、再利用された標準レコード、解決された判断）を、曖昧さなく記述します。--plan モードでは、各リーフの実際の処理状況（reused／action_needed／保留中）と、コーディネーターの計画 JSON（dry_run: true）を記載します。各リーフは、完全な JSON 結果（作成されたすべてのレコード Id と deploy Id を含む）も、実行のアーティファクトディレクトリ内にあるスキルごとのアーティファクトに書き込みます。これが監査証跡です。ユーザー向けの出力では、レコード Id ではなく人が読める名前を使用します。レポートの形式については、examples/output-templates.md を参照してください。

実行アーティファクト（run モード）。 スキルごとのアーティファクトに加えて、--run は実行のアーティファクトディレクトリに次の3つのファイルを書き込みます（レポート JSON には、パスが run_log、deploy_ids_file、teardown_script として記載されます）。run.log（サニタイズ済みで、人が読める手順と結果）、deploy_ids.json（出所を示すマニフェスト。各エントリの provenance は created／updated／reused のいずれかで、リソース ID、before スナップショット、正規のスキルごとのアーティファクトへのポインターを含みます）、および teardown.sh（自動生成される、dry-run の逆依存順プラン）。teardown スクリプトは、teardown で REMOVE（実行時に作成）、RESTORE（更新済みで、以前の値に復元）、または KEEP（採用済み／再利用済み。削除しない）となる項目を出力しますが、変更は加えません。破壊的な実行は、意図的に手動のままとしています（「制限事項」を参照）。

レポート内容のルール：

• 意図ではなく、具体的な結果を報告します。
• セットアップが実行された場合は、オペレーターがラジオをオンにするのを断った場合でも、ログイン動作のクリック手順を必ず明示します。
• ステップ5でのハード失敗（キューがバインドされていないこと）は、クリック手順を添えて手動操作として明示します。

制限事項

• ルーティングフローのデプロイ対象は Case と VoiceCall のみです。
• 対象は Classic OmniSupervisorConfig（アクションとタブの表示要素を含む）のみです。Command Center V2（Enhanced Omni-Channel）は読み取り専用の分析ステップで報告されますが、有効化されません。組織の設定は Metadata API では書き込みできません。表示要素のリーフが追加するのは、参照を必要としない標準アクション／タブの種類のみです。カスタムアクション、FlexiPage、AWS ダッシュボード、AI エージェントの表示要素には外部参照が必要なため、Setup で設定する必要があります。
• 担当者エクスペリエンスのステージ（プレゼンスのユーザー設定、辞退理由、サイドバー）は、OMNI_REP_EXPERIENCE=1 の場合のみ実行されます。SkillsBased ルーティングは明示的に選択されるか、完全な OMNI_WSR_* マッピングから推定され、上記のフラグとは独立して実行されます。
• Teardown は プランのみです。--run は deploy_ids.json（出所を示すマニフェスト）と、逆順の削除／復元プランを出力する dry-run の teardown.sh を生成しますが、破壊的な変更は実行しません。自動的なロールバックは、すべてのリーフが正規化された出所ブロックを出力し、ライブ環境でロールバックが検証されるまで、意図的に延期されています。Metadata API でデプロイされたコンポーネントには destructiveChanges のデプロイが必要であり、採用済みのレコードは決して削除してはなりません。現在、ロールバックはプランとスキルごとのアーティファクトを参考に、オペレーターが手動で行う作業です。

ユースケースの対応状況（現在）

ユースケース	ステータス	ヘッドレス対応の内容
ケースのルーティング	対応済み	作成から関連付けまでの一連の処理（キュー + QRC + メンバー + ルーティングフロー）に完全対応し、冪等性があります。実行時の PendingServiceRouting による証明は任意です。
VoiceCall / AFCC のルーティング	条件付き	QRC + キュー + メンバー + ルーティングフローはデプロイ可能ですが、エンドツーエンドで証明するには、プロビジョニング済みの Amazon/AFCC コンタクトセンターと稼働中の Voice ランタイムが必要です。コンタクトセンターのプロビジョニングは呼び出し元の責任です。
Open CTI → AFCC の移行	部分対応	コーディネーターは Omni ルーティングリソースを作成しますが、コンタクトセンター自体のプロビジョニングや移行は行いません。
インシデントのルーティング	部分対応	サービスチャネル + プレゼンスに対応しています。コーディネーターはインシデントのルーティングを検証／採用しますが、不足しているキュー／QRC／フローは作成しません。
汎用的な MessagingSession のルーティング	部分対応	サービスチャネル + プレゼンスに対応しています。作成から関連付けまでの一連の処理は service-agentforce-human-escalation-configure に委任されており、ここでは汎用的に実行されません。
Classic Omni Supervisor	対応済み	ユーザー、権限、設定、キュー／ユーザー、およびアクション／タブのサーフェスに関する補完機能がすべて実装されています。
Command Center V2	検出のみ	読み取り専用の分析ステップで Classic と V2 を判別します。組織の設定 CommandCenterForServiceV2 はMetadata API では書き込みできないため（追跡 ID：W-23827287）、Setup で有効にする必要があります。
Supervisor 監視の OrgValues	未実装	OmniSuperConvMonitor、OmniSuperAgentSneakpeek、OmniSuperClientSneakpeek、OmniSuperWhisper、OmniSuperAdminSkillQueue は、サポート対象であることが実証された外部書き込み API がない OrgValues です。
Omni Inbox	未実装	サイドバーのリーフは Omni サイドバー（isOmniPinnedViewEnabled）を固定します。Omni Inbox、コンソールアプリ、ユーティリティ項目の作成や設定は行いません。

リファレンス

ファイル	参照するタイミング
references/gap-catalog.md	ヘッドレス対応のギャップ（ログイン動作のラジオボタン、Agentforce のルーティング先、Field Service のスキルルーティング）と、コーディネーターによる各ギャップへの対応方法
examples/output-templates.md	レポートを出力する前 — 標準の Setup Summary、Skill Outcomes、Manual Actions ブロック