service-omni-base-settings-configure

service-omni-base-settings-configure

5 つの OmniChannelSettings ブール値（enableOmniChannel、enableOmniAutoLoginPrompt、enableOmniSecondaryRoutingPriority、enableOmniSkillsRouting、enableOmniStatusCapModel）を、単一の Metadata API デプロイで有効にします。enableOmniChannel=true でなければ、その後のキュー、プレゼンスステータス、ルーティングフローなどは機能しないため、これは Omni のセットアップ手順で最初に行う書き込みである必要があります。このスキルは最初に状態を確認し、いずれかのトグルが false または未設定の場合にのみデプロイします。

入力

bash scripts/configure-and-report.sh run  <org-alias>   # detect; deploy if needed; re-verify
bash scripts/configure-and-report.sh plan <org-alias>   # read-only: detect only, never deploys

org-alias が唯一の入力です。5 つのトグルはすべて常に true に設定されます。このスキルではトグルごとの上書きはできません。一部のみを有効にしたい場合は、独自の OmniChannel.settings-meta.xml を指定して platform-metadata-deploy を使用してください。

前提条件と安全性

• 対象の組織が sf CLI で認証済みであること（.lightning.force.com ではなく My Domain URL を使用）、Service Cloud ライセンスがあること、sf CLI が 2.139.6 以降であること。
• 本番環境の安全策： 書き込み処理は、IsSandbox が true、または TrialExpirationDate != null、または OrganizationType が {Developer Edition, Base Edition} のいずれかであれば safe_to_write を true と判定します。これが false の場合、上書き手段はなく、処理をブロックします。この条件では CDO（IsSandbox=false かつ TrialExpirationDate が null 以外）も許可されます。単純な IsSandbox のチェックに弱めないでください。

実行

configure-and-report.sh が正式なエントリーポイントです。

• run — 状態を確認します。5 つすべてがすでに有効なら reused を出力し（デプロイなし）、そうでなければ safe_to_write ガードを実行し、5 つすべてを true に設定した明示的な assets/force-app/main/default/settings/OmniChannel.settings-meta.xml ソースファイルをデプロイします（SucceededPartial は失敗として扱います）。その後、再度状態を確認し、5 つすべてが true になっていれば configured、そうでなければ blocked を出力します。明示的なソースパスを指定することで、組織の値が変化している場合に、ソーストラッキングによるデプロイ不要の判定を回避します。
• plan — 状態の確認のみを行います。すべて有効なら reused、そうでなければ action_needed を出力します。デプロイは行いません。

状態の確認では Settings:OmniChannel を取得します。Metadata の取得には時間がかかるため、1～2 分ほどかかりますが、これは想定どおりです。デプロイは（有効な DX プロジェクトである）assets/ から実行し、--source-dir で設定ファイルを指定します。実行時にテンプレートが変更されることはないため、このスキルの再現性が保たれ、ローカルのソーストラッキングに変更がないという理由だけで「No local changes to deploy」と報告されることもありません。

動作

ドキュメント全体の書き込み。 Settings はドキュメント全体を扱うメタデータ型です。Metadata API は部分更新を受け付けないため、このスキルは個々のトグルを PATCH するのではなく、常にファイル全体をデプロイします。

ログイン動作に関する制約。 Omni のログイン動作ラジオボタン（Setup → Omni-Channel Settings →「エージェントが新しいウィンドウ／タブを開いたときのログイン動作を定義」）には、v66 で公開 API がありません。レポートには、処理不要の reused 実行時も含め、常に操作画面への移動手順が表示されます。そのため、「実行することなし」という結果でも、手動操作が必要な唯一の項目が隠れることはありません。enableOmniAutoLoginPrompt は問題なくデプロイされます（ほかの Omni 機能が内部的に依存している可能性があります）が、このラジオボタンの動作には影響しません。

失敗時は安全側に倒す検証。 デプロイ後、スキルは状態を再確認し、5 つすべてのトグルが true であることを要求します。成功と報告されたデプロイが反映されていない場合（組織レベルの制限によるまれなケース）は、成功を報告せず、処理をブロックします。

出力契約

configure-and-report.sh は、status が configured | reused | action_needed | blocked のいずれかである単一の JSON オブジェクトを出力します。このオブジェクトには、コーディネーターが後続のスキルを実行するかどうかの判定に使うトップレベルの all_enabled ブール値、完全な before／after トグルオブジェクト、deploy_id、safe_to_write、manual_actions、blocking_issue が含まれます。

• configured — トグルが false で、デプロイが実行され、再プローブですべて true と確認された場合（実行モード）。
• reused — 5 つすべてがすでに true で、デプロイは行われない場合。
• action_needed — プランモードで無効なトグルが見つかり、何もデプロイされなかった場合。
• blocked — safe_to_write=false の場合、デプロイが失敗した場合、または SucceededPartial だった場合、あるいは再プローブで false のトグルが残っていた場合。

ブロックされていないレポートでは、manual_actions に常にログイン動作に関するギャップの項目が含まれます。reused／action_needed の場合、deploy_id は null です。blocking_issue には、status: blocked の場合に限り、失敗の内容が示されます。

制限事項

• OmniChannelSettings のみを設定し、常に 5 つすべてのトグルを true にします。他の Settings タイプは platform-metadata-deploy の対象です。
• ログイン動作のラジオボタンは変更できません（v66 では公開 API がありません）。クリック手順を提示するのみです。

参考資料

ファイル	参照するタイミング
references/api-notes.md	デプロイ前 — 5 つのトグルの意味、依存関係、ログイン動作に関する注意事項