service-omni-presence-status-deploy

service-omni-presence-status-deploy

sObject固有の Available_<X> ServicePresenceStatusを、そのsObjectのServiceChannelに紐付けてデプロイし、ユニバーサルな Busy ステータスが存在することを、単一のアトミックなMetadata APIデプロイで確認します。すべてのOmniエージェントには、チャネルを持つ「作業可能」ステータス（受信した作業をルーティングするため）と、「勤務外」ステータス（作業から離れられるようにするため）が必要です。プレゼンスステータスはDeveloperNameによって1つのServiceChannelのみに紐付くため、各ルーティング対象に専用のAvailableステータスが必要です。このスキルは、エージェントにこのスキルがデプロイするステータスへのアクセス権を付与する service-omni-permission-set-assign と組み合わせて使い、service-omni-channel-setup-coordinate によってルーティング対象ごとに1回呼び出されます。

対象sObject	Availableステータス	紐付けられたチャネル
Case	Available_Case	Cases
Incident	Available_Incident	Incidents
MessagingSession	Available_Messaging	sfdc_livemessage
VoiceCall	Available_Voice	sfdc_phone

BusyはUIで定義され、メタデータでは定義されません。 Omniの「Busy vs Online」オプションはMetadata APIでは表現できません。ServicePresenceStatus が持つのは <label> と <channels> のみで、チャネルを持たないステータスはBusyとして扱われます。慣例上、BusyのDeveloperNameは単に Busy であり、ほとんどの組織にはすでに存在するため、このスキルは既存の Busy を再利用し、存在しない場合に限って同梱アセットをデプロイします。作業を受信するためにBusyステータスは必要ありません。ルーティングを担うのは、チャネルを持つAvailableステータスです。

入力

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

• org-alias（必須）。
• sobject_type（省略可能、デフォルトは Case）。

前提条件と安全性

• 対象組織が sf CLI（My Domain URL）で認証済みであること、Service Cloudライセンスがあること、sf CLI ≥ 2.139.6であること。
• Omni-Channelの基本設定が有効になっていること（service-omni-base-settings-configure）。そうでない場合、デプロイは INVALID_TYPE で失敗します。
• 対象sObjectのServiceChannelが存在すること（service-omni-service-channel-configure）。そうでない場合、デプロイは Value '<channel>' is not valid で失敗します。Incident にはIncident Management機能の有効化が必要です。MessagingSession にはEnhanced Messagingが必要です。
• 3段階の safe_to_write 本番環境ガードが適用されます。

実行

deploy-and-report.sh は、Available_<X> ステータス（および組織に存在しない場合に限り Busy）を1回のMetadata API呼び出しでデプロイし、各コンポーネントの files[].state をスキルのステータスに対応付けます。

• reused — すべてのコンポーネントが Unchanged。
• updated — いずれかのコンポーネントが Changed で、Created はない。
• created — いずれかのコンポーネントが Created。

個別の検出ステップはありません。Salesforceの files[].state が正とされます。デプロイでは明示的な --metadata フラグを使用し（--source-dir は使用しません）、無関係なアセットが一緒にデプロイされないようにします。

動作

再デプロイより再利用を優先します。 既存の Busy は検出され、そのまま保持されます。デプロイされるのは、存在しない場合のみです。このスキルは、自身がデプロイしていないプレゼンスステータスを削除したり上書きしたりしません。組織には他のカスタムステータス（Omni_OnBreak、availableForMiaw など）が含まれていることがよくあります。

スキーマ。 XMLでは <statusType> を省略します（v66で削除され、onlineかbusyかは <channels> の有無から推定されます）。また、このスキルは StatusType をSOQLクエリしません（v66ではクエリできず、信頼できる項目はId、DeveloperName、MasterLabelのみです）。Available_Messaging は、Enhanced Messagingに必ず含まれる標準の sfdc_livemessage チャネルに紐付けられます。

出力の仕様

単一のJSONオブジェクトで、status は created | reused | updated | blocked のいずれか、さらに sobject_type、presence_statuses 配列（各要素に developer_name、label、channels、state を含み、Busy の場合は reused_existing も含む）、deploy_id、manual_actions、blocking_issue を含みます。

• blocked — デプロイ失敗（前提条件の不足、スキーマの不一致、または組織エラー）。manual_actions には実行すべき前提スキルが示され、blocking_issue にはSalesforceのエラーがオペレーターにわかりやすく翻訳されます。
• deploy_id はすべての実行で設定されます（変更のないデプロイでもSalesforceから発行されます）。

制限事項

• Available_<X> と Busy のペアのみをデプロイします。カスタムステータスを使用するには、assets/servicePresenceStatuses/*.xml をフォークする必要があります。
• 対象は Case、Incident、MessagingSession、VoiceCall のみです。対象を追加するには、ディスパッチャーの分岐と対応するアセットを追加してください。
• PresenceUserConfig の容量や辞退理由は設定せず、既存のステータスを削除することもありません。

参考資料

ファイル	読むタイミング
assets/package.xml	選択した Available ステータスと任意の Busy ステータスを対象に、明示的な Metadata API デプロイを準備するときに読み込みます
references/api-notes.md	予期しないデプロイ動作が発生したときに読み込みます。v66 XML スキーマ（statusType なし）、チャネルのバインディング規則、MessagingSession 固有の注意事項を確認できます