service-omni-service-channel-configure

service-omni-service-channel-configure

ルーティング可能な sObject ごとに ServiceChannel が正確に 1 つ存在するようにします。すでにバインドされているチャネル（Salesforce 標準チャネルまたは既存のカスタムチャネル）があればそれを再利用し、存在しない場合に限り、スキルの正規 v66 テンプレートをデプロイします。Salesforce では RelatedEntity ごとに 1 つの ServiceChannel しか許可されないため、このスキルは最初に検出を行い、決して無条件にデプロイしません。すでにチャネルがある sObject に 2 つ目のチャネルをデプロイすると、"This Salesforce object is already in use by another Service channel." というエラーが発生します。1 回の呼び出しで扱う sObject は 1 つです。複数の sObject を設定する場合は、service-omni-base-settings-configure で Omni-Channel を有効にした後、sObject ごとに 1 回ずつ呼び出します。

sObject	標準チャネル（該当する場合）	正規アセット
Case	Cases	Cases.serviceChannel-meta.xml
Incident	なし（Incident Management sObject）	Incidents.serviceChannel-meta.xml — 初回実行時にデプロイ
MessagingSession	sfdc_livemessage	MessagingSessions.serviceChannel-meta.xml — 標準チャネルがない場合に限りデプロイ
VoiceCall	sfdc_phone	VoiceCalls.serviceChannel-meta.xml — 標準チャネルがない場合に限りデプロイ

入力

bash scripts/deploy-and-report.sh <org-alias> [Case|Incident|MessagingSession|VoiceCall]

• org-alias（必須）。
• sobject_type（任意、デフォルトは Case）— Case | Incident | MessagingSession | VoiceCall のいずれか。

前提条件と安全性

• 対象組織が sf CLI（My Domain URL）で認証済みであること、Service Cloud ライセンスがあること、sf CLI が 2.139.6 以降であること。
• Omni-Channel の基本設定が有効であること（service-omni-base-settings-configure）。enableOmniChannel=true の場合に限り、ServiceChannel のクエリと書き込みが可能です。デプロイ時の INVALID_TYPE は、基本設定がオフであることを意味します。
• Incident には Incident Management 機能の有効化が必要です。MessagingSession には Enhanced Messaging が必要です。このスキルは最初に EntityDefinition を検証し、対象 sObject が存在しない場合はクリックパスを示して処理を中断します。

実行

deploy-and-report.sh は前提条件の確認、検出、必要な場合に限ったデプロイを行い、その後レポートを出力します。

1. 前提条件 — 対象 sObject が EntityDefinition 経由でクエリ可能であることを確認します。そうでない場合はクリックパスを示して処理を中断します。
2. 検出 — Tooling API にクエリを実行し、RelatedEntity = <sobject_type> に該当する ServiceChannel を探します。v66 では ServiceChannel は Tooling エンティティです。標準の Data API は INVALID_TYPE を返します。見つかった場合は再利用します。
3. デプロイ（何も見つからなかった場合に限る）— 正規 XML（Cases | Incidents | MessagingSessions | VoiceCalls）を sf project deploy start でデプロイします。状態が Changed の場合は created、Unchanged の場合は reused です。

動作

検出してから再利用またはデプロイ。 Salesforce は RelatedEntity ごとに 2 つ目のチャネルを拒否するため、先にデプロイする方法は安全ではありません。たとえば、オペレーターが標準の Cases チャネルの名前を変更している場合、適切に再利用されず、"already in use" エラーが発生します。Tooling API による検出は高速で、1 回の呼び出しで再利用の判断と検出された DeveloperName の両方を取得できます。その代わり、このスキルでは「正規の構成と一致する」場合と「何らかのカスタムチャネルがバインドされている」場合を区別できません。正規の構成ではないチャネルがある場合は reused となり、そのチャネルには変更を加えません（v1 ではオペレーターの状態を上書きしません）。

容量モデル。 正規アセットはすべてのバリエーションで TAB_BASED を使用します。STATUS_BASED には完全なスキーマが文書化されていない付随フィールドが必要なため、対象外です。エージェントごとの容量調整は、このスキルではなく PresenceUserConfig.Capacity で行います。

同時実行。 デプロイ時に "already in use" エラーが発生した場合は、検出からデプロイまでの間に別のプロセスがチャネルを作成しています。このスキルはソフトフェイルし、再実行するとそのチャネルを再利用します。

出力契約

呼び出しごとに、status ∈ created | reused | blocked と、sobject_type、channel_developer_name、channel_id、channel_origin、target_capacity_model、target_related_entity_type、before_state、deploy_id、manual_actions、blocking_issueを含む単一の JSON オブジェクトを返します。

• reused — 既存のチャネルが見つかった場合（検出でヒットした場合、またはデプロイの結果が Unchanged だった場合）。
• created — チャネルが存在せず、正規の XML が Changed でデプロイされた場合。
• blocked — sObject が org に存在しない場合、基本設定がオフの場合（INVALID_TYPE）、または競合によりチャネルがすでに使用中になった場合。
• channel_origin は salesforce_standard（sfdc_* 形式の名前または Cases）、canonical_asset（同梱アセットの名前）、canonical_template（今回新たにデプロイ）、custom（org 固有の既存チャネル）のいずれかです。
• チャネルが存在する場合、channel_id に値が設定されます（blocked の場合は null）。deploy_id に値が設定されるのはデプロイ分岐の場合のみです。blocking_issue が null 以外になるのは、status: blocked の場合のみです。

制限事項

• 呼び出しごとに 1 つの sObject を処理します。
• 対応しているのは Case、Incident、MessagingSession、VoiceCall のみです。対応対象を追加するには、assets/force-app/main/default/serviceChannels/<Name>.serviceChannel-meta.xml ファイルとディスパッチャーの分岐を追加してください。
• 既存のチャネルは常に再利用されます。設定が正規の形式と異なるチャネルを、正規の形式にリセットすることはありません。

参照資料

ファイル	読むタイミング
references/api-notes.md	想定外の検出結果、デプロイの失敗、または sObject 固有のスキーマに関する質問がある場合