service-omni-queue-deploy

service-omni-queue-deploy

要求されたルーティング可能な sObject に対する QueueSobject のバインドがある Group（Type='Queue'）が存在することを確認し、既存のものがあれば再利用します。--create-if-missing を指定すると、バインドされたキューがない場合に Metadata API 経由でキュー（Group + QueueSobject）を作成し、必要に応じて QueueRoutingConfigId を呼び出し元が指定した QRC に合わせます。このスキルはキューを名前ではなく、QueueSobject.SobjectType のバインドを使って検出します。実際の組織ではキューの名前に一貫性がなく（CaseQueue、messagingqueue、Omni_Demo_Cases_Queue など）、キューとサポートするルーティングの機能上の関連付けは DeveloperName ではなくバインドだからです。これは service-omni-channel-setup-coordinate によって呼び出されます。キューのメンバー割り当ては別のリーフ（service-omni-queue-members-assign）であり、このスキルが合わせる QRC は service-omni-queue-routing-config-deploy から取得します。

入力

bash scripts/verify-and-align.sh <org-alias> [Case|Incident|MessagingSession|VoiceCall] [routing_config_dn] [queue_developer_name] [--create-if-missing]
# create + bind a Voice queue on a fresh org:
bash scripts/verify-and-align.sh myorg VoiceCall Voice_Routing_Config "" --create-if-missing

• org-alias（必須）。
• sobject_type（任意、デフォルトは Case）。
• routing_config_dn（任意） — 指定すると、その QRC に強制的に合わせます。Case で省略した場合は Case_Routing_Config がデフォルトになります。他の sObject で省略した場合は、強制的な変更を行わず既存のバインドを報告します。
• queue_developer_name（任意の第 4 位置引数） — 操作対象とする明示的なキュー、または --create-if-missing で作成するキューの名前。
• --create-if-missing（フラグ、または QUEUE_CREATE_IF_MISSING=1）— バインドされたキューがない場合に Metadata API 経由でキューを作成します。ラベルは DeveloperName をスペース区切りにした形式がデフォルトです（QUEUE_LABEL で上書きできます）。

前提条件と安全性

• 対象組織が sf CLI で認証済みであること（My Domain URL）、Service Cloud ライセンスがあること、sf CLI が 2.139.6 以降であること。
• 対象の sObject が組織で有効になっていること — 書き込みの前に EntityDefinition で確認します。sObject が存在しない場合は、機能を有効にするための設定画面への移動手順とともに処理を停止します（Incident の場合は Incident Management、MessagingSession の場合は Enhanced Messaging）。
• routing_config_dn が指定されている場合、その QRC がすでに存在している必要があります（DeveloperName で解決）。存在しない場合は、service-omni-queue-routing-config-deploy を参照するよう案内して処理を停止します。
• 3 段階の safe_to_write 本番環境ガードが適用されます。

実行

verify-and-align.sh は一連の処理を実行し、レポートを出力します。

1. 前提条件 — EntityDefinition で sObject を確認します。
2. 検出 — QueueSobject WHERE SobjectType = '<sobject_type>'。該当するものがあれば再利用します。該当するものがなければ、--create-if-missing の指定時は Metadata API 経由で作成します。それ以外の場合は、設定画面への移動手順を示して処理を停止します。
3. 確認 — キューの QueueRoutingConfigId と QueueSobject の全リストを読み取ります。
4. 調整（任意） — routing_config_dn が指定されている場合は、その Id を解決し、ずれがあれば Group.QueueRoutingConfigId に PATCH します。
5. 再クエリ — 収束を確認して JSON を出力します。

動作

名前より検出を優先します。 QueueSobject が対象の sObject へのルーティングを設定しているキューは、名前にかかわらず、その sObject のキューです。名前で判定すると、messagingqueue のようなキューを見落とし、処理をブロックしたり、重複して作成したりする可能性があります。

作成は冪等です。 メタデータのデプロイは fullName をキーにアップサートするため、--create-if-missing は同じ名前の既存キューを採用・更新し、2つ目のキューは作成しません。作成時に適用するのは、安全性を確保するための最小限の設定（doesSendEmailToMembers=false と sObject のバインド）です。また、既存の QueueSobject 行は削除しません。同じキューを経由するよう意図的にルーティングされた別の sObject がある可能性があるためです。

強制された QRC と検出された QRC。 Case では、コーディネーターが Case_Routing_Config との確実な整合を求めるため、スキルはこれを強制します。コーディネーターが管理する QRC のないその他の sObject では、存在しない可能性のある名前を強制せず、キューにすでに設定されているものを報告します（source: discovered）。QRC Id は実行時に DeveloperName で解決し、ハードコードしません。

曖昧さへの対応。 同じ sObject に複数の異なるキューがバインドされている場合、スキルは推測せず、オペレーターに判別を求めて処理をブロックします。ただし、標準名が一致する場合、または明示的な queue_developer_name で正確なキューが指定されている場合を除きます。

PATCH の安全性。 sf api request rest は stderr にベータ版の警告を出力します。スキルは stderr を個別に取得し、JSON の解析を妨げないようにします。また、PATCH 時にはキューの Id を維持します（削除して再作成することはありません）。後続の参照先がこの Id を指しているためです。

出力の仕様

単一の JSON オブジェクトを返します。status の値は created | reused | updated | blocked のいずれかで、さらに sobject_type、developer_name、queue_created、id、queue_routing_config_id、queue_routing_config_developer_name、queue_routing_config_source（forced | discovered）、queue_sobjects、before スナップショット、manual_actions、blocking_issue を含みます。

• created — キューがバインドされておらず、--create-if-missing によって（指定された QRC をバインドして）作成された場合です。
• reused — バインド済みのキューがあり、QRC が渡された場合はすでに一致している場合です（PATCH は実行されません）。
• updated — バインド済みのキューはありますが、呼び出し元から渡された QRC と一致せず、PATCH が実行された場合です。
• blocked — sObject が存在しない、バインド済みのキューがなく --create-if-missing も指定されていない、指定された QRC が存在しない、または再クエリー後に状態が収束しなかった場合です。

queue_created が true になるのは、この実行で新しいキューがデプロイされた場合のみです。blocking_issue は失敗した前提条件を具体的に示し、manual_actions はクリック操作の手順を示します。

制限事項

• 対象は Case、Incident、MessagingSession、VoiceCall のみです。対象を追加するには、ディスパッチャーの分岐を追加してください。
• キューやその QueueSobject 行は削除せず、キューメンバーも変更しません。
• 作成時に設定するのは最小限のキュー構成です。特殊なフィールド（doesIncludeBosses、メールルーティングアドレス）は設定されません。

参考資料

ファイル	読むタイミング
references/api-notes.md	キューが見つからず処理がブロックされた場合（手動クリック操作の手順）、または予期しない Data API エラーが発生した場合。Queue／QueueSobject のスキーマ、Metadata API による作成形式、stderr の分離、キュー名の揺れに関する注意事項を記載しています。