service-omni-supervisor-config-deploy

service-omni-supervisor-config-deploy

従来の Omni-Channel Supervisor Configuration（OmniSupervisorConfig）を、単一の Metadata API デプロイで Salesforce 組織にデプロイします。OmniSupervisorConfig は、XSD にすべての付随要素が繰り返し可能な子要素として組み込まれた完全な Metadata API タイプです。そのため、親と付随要素を含む構成全体を、1 つの .omniSupervisorConfig-meta.xml ファイルからアトミックにデプロイでき、一部で失敗した場合も Salesforce が付随要素をまとめてロールバックします。デフォルトでは、スーパーバイザーをユーザー単位で明示的に割り当て、監視するキューを指定します。プロファイルのスコープは任意です（「動作」を参照）。

入力

bash scripts/deploy-and-report.sh <org-alias> [supervisor_count] [additional_queues_csv] [profiles_csv] [skill_visibility] [config_developer_name]

• org-alias（必須）— sf org display --target-org <alias> で解決できる必要があります。
• supervisor_count（任意、デフォルトは 1、範囲は 1..5）— 検出して割り当てる、アクティブな supervisor{N}.<suffix>@example.com ユーザーの数です。
• additional_queues_csv（任意）— 割り当てるキューの DeveloperName です。コーディネーターからこのリストが渡された場合、その内容が正となります。省略した場合は、標準のデフォルトである CaseQueue と messagingqueue が使用されます。指定するキューはすべて、組織にすでに存在している必要があります。
• profiles_csv（任意）— プロファイルベースのフォールバックスコープを有効にします。メタデータの profile fullName を指定します（例：Standard,ServiceCloud）。省略すると、スーパーバイザーはユーザー単位でのみ割り当てられます。
• skill_visibility（任意、または OMNI_SUPERVISOR_SKILL_VISIBILITY）— AllSkills または AnySkill を指定します。省略した場合、既存の構成では選択内容が維持され、新規構成ではデフォルトとして AllSkills が設定されます。
• config_developer_name（任意、または OMNI_SUPERVISOR_CONFIG_DEVELOPER_NAME。デフォルトは Omni_Supervisor）— 作成または調整する、従来の OmniSupervisorConfig.DeveloperName を正確に指定します。組織に複数のスーパーバイザー構成がある場合に指定してください。このスキルが候補の中から推測することはありません。OMNI_SUPERVISOR_CONFIG_MASTER_LABEL を指定すると、新しい構成のラベルを設定できます。既存のラベルはデフォルトで維持されます。

前提条件と安全性

• ターゲット組織が sf CLI で認証済みであること、Service Cloud ライセンスがあること、sf CLI のバージョンが 2.139.6 以上であること。
• アクティブなスーパーバイザーユーザーが存在すること。スーパーバイザーアクセスの付与は、別途 service-omni-supervisor-permset-assign によって行います。
• Omni-Channel の基本設定が有効であること（service-omni-base-settings-configure）。監視対象のキューが存在すること（service-omni-queue-deploy）。
• 本番環境のガードレール： スクリプトは IsSandbox OR TrialExpirationDate != null OR OrganizationType が {Developer Edition, Base Edition} に含まれる、という条件で safe_to_write を計算します。条件が false の場合、オーバーライドなしでは処理をブロックします。前提条件が満たされない場合は、blocking_issue とクリックパスを含む status: blocked が返されます。

実行

1 つのスクリプトで検出、デプロイ、検証を行います。

bash scripts/deploy-and-report.sh <org-alias> [supervisor_count] [additional_queues_csv] [profiles_csv] [skill_visibility] [config_developer_name]

稼働中の組織の状態（検出したスーパーバイザーユーザー、検証済みのキュー、および profiles_csv が指定された場合に限り検証済みのプロファイル）から、デプロイ成果物のトークンを解決します。次に、選択された DeveloperName をメタデータのファイル名とパッケージマニフェストに反映し、その後、同じ選択済みの構成を再クエリして、JSON を標準出力に出力する前に親要素と付随する行が保存されたことを確認します。コーディネーター（service-omni-channel-setup-coordinate）は、正として扱うキューリストと選択済みのスーパーバイザー構成を指定してこのスクリプトを呼び出します。単独で実行する場合は標準のデフォルトが使用されます。

動作

コンパニオン。 デプロイされる設定には、常に omniSupervisorConfigUser（スーパーバイザーごとに 1 つ）と omniSupervisorConfigQueue（監視対象のキューごとに 1 つ）が含まれます。service-omni-service-channel-configure および service-omni-presence-status-deploy と同じ、単一ファイルの Metadata デプロイ形式に従います。

プロファイルのスコープはデフォルトでは無効のフォールバックです。 Core は、まず OmniSupervisorConfigUser を使ってスーパーバイザーの設定を解決し、スーパーバイザーにユーザー行がない場合に限り、OmniSupervisorConfigProfile にフォールバックします。照合対象はそのスーパーバイザー自身のプロファイルです（RealTimeQueueServiceImpl.getSupervisorConfigId）。このスキルではすべてのスーパーバイザーをユーザー単位で紐付けるため、profiles_csv を渡さない限り、プロファイルのコンパニオンは不要であり、省略されます。指定する場合、値には Metadata の fullName を使用する必要があります（<profile> 要素は SOQL の User.Profile.Name ラベルではなく、fullName（Standard、ServiceCloud、Admin）に照合されます）。このスキルは各値を sf org list metadata -m Profile に対して検証し、組織で公開されていないものがあれば処理をブロックします。

冪等性とサーフェスの保持。 ステータスは Metadata デプロイのコンポーネント状態に従います。Unchanged → reused、Changed → updated、Created → created です。それ以外の状態は、暗黙に reused とするのではなく、ハードエラーになります。既存の親を更新する前に、このスキルは参照のない OmniSupervisorConfigAction および OmniSupervisorConfigTab の行をスナップショットし、安全に再作成できることを検証してから、デプロイ後に復元し、再クエリします。カスタムサーフェスや参照を持つサーフェスがある場合、意図せず失われるリスクを避けるため、デプロイ前に処理をブロックします。既存の設定を調整する場合や保持を検証する場合は、このスキルのみを呼び出してください。service-omni-supervisor-surface-deploy は呼び出さないでください。後から標準行を追加すると、保持に失敗していても隠れてしまう可能性があります。コンパニオンのサーフェススキルは、新しい標準アクションやタブの追加を別途依頼された場合にのみ対応します。

フェイルクローズ検証。 デプロイの status は Succeeded でなければならず（SucceededPartial は不可）、親設定をクエリできるようになった後、スクリプトは子の OmniSupervisorConfigUser および OmniSupervisorConfigQueue の行を再クエリし、少なくとも指定した数があることを必須とします。親が存在するだけでは、コンパニオンが反映された証明にはなりません。すべての読み取りで、解析可能な .result.records 配列が返されなければなりません。結果が確定できない読み取りをゼロ件として扱うことはありません。指定されたキューは使用前に ^[A-Za-z0-9_]{1,80}$ に対して検証され、指定したキューはすべて存在する必要があります。1 つでも存在しない場合は処理がブロックされます（暗黙に除外すると、設定が不足するためです）。

出力の仕様

標準出力には単一の JSON オブジェクトを出力します。status は created、updated、reused、blocked のいずれかです。オブジェクトには、config_developer_name、config_id、skill_visibility、スナップショットと復元の件数を示す surface_preservation、supervisor_users_bound／supervisor_users_count、queues_bound／queues_count、queue_source（caller_supplied または canonical_default）、再クエリで検証した verified_companion_user_count／verified_companion_queue_count、deploy_id、state、manual_actions、blocking_issue も含まれます。status: blocked でない限り、blocking_issue は null です。status: blocked の場合は、不足している前提条件を示し、manual_actions にクリック操作の経路を記載します。変更のない設定を再実行すると reused が返され、機能上の変更は行われません。

組織側のスポットチェック：

SELECT Id, DeveloperName, MasterLabel FROM OmniSupervisorConfig WHERE DeveloperName='<config_developer_name>'
SELECT COUNT(Id) FROM OmniSupervisorConfigUser  WHERE OmniSupervisorConfigId = :configId
SELECT COUNT(Id) FROM OmniSupervisorConfigQueue WHERE OmniSupervisorConfigId = :configId

制限事項

• ユーザーとキューの関連レコード（および任意のプロファイルスコープ）を設定します。既存の参照先を持たない Action 行と Tab 行は更新時に保持されます。新しい標準行は service-omni-supervisor-surface-deploy によって別途追加されます。Custom-action、FlexiPage、AWS-dashboard、AI-agent の各行には外部参照が必要なため、不完全な状態で再構築するのではなく、更新を中断します。
• supervisor{N}.<suffix>@example.com のパターンで検出したスーパーバイザーユーザーを紐付けます。ユーザーは作成しません。
• AgentWork の共有設定は変更しません。これは組織全体のアクセス制御であり、OmniSupervisorConfig とは別の設定です。サポートされているメタデータの検出と、明示的に確認された Private から Read への変更には、service-omni-agent-work-sharing-configure を使用してください。
• Command Center V2 ランタイムは有効化しません（別途設定の切り替えが必要です）。

参照資料

ファイル	読むタイミング
references/api-notes.md	デプロイ失敗時 — OmniSupervisorConfig のフィールド別スキーマと関連 sObject のセマンティクス
assets/force-app/main/default/omniSupervisorConfigs/Omni_Supervisor.omniSupervisorConfig-meta.xml	トークンテンプレート化されたデプロイ成果物（__MASTER_LABEL__、__SUPERVISOR_USERS_XML__、__PROFILE_SCOPE_XML__、__QUEUE_LIST_XML__、__SKILL_VISIBILITY__）。実行時に、選択した DeveloperName の下に実体化されます
assets/package.xml、assets/sfdx-project.json	一時デプロイディレクトリに実体化されるマニフェストとプロジェクトのひな形