service-omni-work-skill-routing-configure

service-omni-work-skill-routing-configure

作業レコードのフィールド値に基づいて作業をエージェントに割り当てる Omni WorkSkillRouting ルールを作成します。エージェントが持つスキルだけに基づいて割り当てるわけではありません。service-omni-skills-based-routing-configure がエージェントを ルーティング可能 にする（Skill + ServiceResource + ServiceResourceSkill）のに対し、このスキルは、作業項目のフィールドの値に基づいて、どのスキルが必要か を判断します。たとえば、「Case.Origin = Phone の場合、Voice スキルを必須とする」といったルールです。このルールは、1 つの WorkSkillRouting レコード（ヘッダーと 1 つの workSkillRoutingAttributes マッピング）で構成され、Metadata API を介してデプロイされます。参照先の Skill が存在し、service-omni-channel-setup-coordinate が調整する同じルーティングファミリーに属している状態で実行します。

入力

bash scripts/configure-and-report.sh <org-alias> <related_entity> <field> <skill> <value> [rule_master_label]

• org-alias（必須）。
• related_entity（必須）。ルールを適用する sObject（例：Case、MessagingSession、LiveChatTranscript、Lead、VoiceCall）。
• field（必須）。属性が評価するフィールド（例：Case.Origin または Origin）。修飾されていない標準フィールドは、デプロイ前に関連エンティティで修飾されるため、Origin がカスタムフィールドのメタデータ名として誤認されることなく、Case.Origin になります。
• skill（必須）。フィールド値が一致したときに必須となる Omni Skill の DeveloperName（例：Voice）。
• value（必須）。フィールド値とスキルを対応付ける値（例：Phone）。通常の値のみを指定できます。XML で予約されている文字はサポートされていません。
• rule_master_label（任意）。ルールの MasterLabel。デフォルトは <related_entity> Skill Routing です。

環境変数による上書き：RULE_DEVELOPER_NAME（ルールの fullName。デフォルトは関連エンティティ名 — エンティティごとに 1 つのルール）、IS_ACTIVE（デフォルトは true）、SKILL_LEVEL（0～10）、SKILL_PRIORITY（0～10。追加スキルの削除順序）、IS_ADDITIONAL_SKILL（true／false）。

前提条件と安全性

• sf CLI で対象の org に認証済みであること、Service Cloud ライセンスがあること、sf CLI が 2.139.6 以上であること。
• Omni-Channel の基本設定が有効で、スキルベースのルーティング がオンになっていること（service-omni-base-settings-configure）。
• 参照先の Skill がすでに存在すること（service-omni-skills-based-routing-configure）。
• 3 段階の safe_to_write 本番環境ガードが適用されます。

実行

1. safe_to_write — Organization をクエリし、実際の本番 org への書き込みを拒否します。
2. Skill の前提条件 — DeveloperName で Skill をクエリします。存在しない場合は処理を中止し、service-omni-skills-based-routing-configure を案内します。
3. マージ — Tooling API を通じて既存の WorkSkillRouting.Metadata を読み取り、無関係な属性を保持したまま、要求された (field, value) マッピングのみを置き換えるか追加します。読み取り結果が不確かな場合は書き込みを中止します。WSR_REPLACE=1 を指定すると、明示的に破壊的な置き換えを許可できます。
4. デプロイ — マージした WorkSkillRouting レコードを実体化し（要素は XSD／アルファベット順）、Metadata API を通じてデプロイします（非同期で実行し、終端状態までポーリングします）。
5. 分類 — files[].state（Created／Changed／Unchanged）を読み取り、created／updated／reused として報告します。

動作

冪等性と安全なマージ。 WorkSkillRouting では関連エンティティごとに 1 つのルールしか使えないため、ルールの fullName はデフォルトでエンティティ名になります。同じマッピングを再実行すると reused と報告され、新しいマッピングは既存の属性リストにマージされ、同じフィールド／値のマッピングを変更すると、そのエントリーのみが更新されます。現在のメタデータを読み取れない場合、このスキルが既存のルールを黙って置き換えることはありません。

グレースフルデグラデーション。 WorkSkillRouting はすべての org でプロビジョニングされているわけではありません（一部のトライアル／CDO では利用できません）。INVALID_TYPE／「not available」／「WorkSkillRouting」の形式のデプロイ失敗は、明確な制限メッセージと基本設定への案内を添えて blocked として報告されます。このスキルはクラッシュするのではなく、制限事項を提示します。

出力コントラクト

単一の JSON オブジェクト：status ∈ created | updated | reused | blocked（プランモードでは action_needed も含みます）、rule（{developer_name, master_label, related_entity, is_active, state}）、attribute（{field, skill, value, skill_level, skill_priority, is_additional_skill}）、merge（{merged_from_existing, attribute_count, preserved_count}）、deploy_id、manual_actions、blocking_issue。

制限事項

• 1 回の呼び出しにつき、フィールドとスキルのマッピングは 1 つ、関連エンティティごとにルールは 1 つです。複数回呼び出すと、そのルールに属性が安全に蓄積されます。
• スキル、ServiceResources、エージェントユーザー、キュー、プレゼンス設定は作成しません。
• フィールドと値の正確性はデプロイ時にプラットフォームによって検証されます。無効なフィールドまたは値は、デプロイ失敗として blocked に反映されます。

参考資料

ファイル	読むタイミング
references/api-notes.md	WorkSkillRouting のメタデータ形式、XSD 要素の順序、関連エンティティごとに 1 つのルールという制約、属性フィールド、縮退動作のトリガーを確認する場合
scripts/tests/test_work_skill_routing_contracts.py	変更を検証する場合 — このスキルのディレクトリから python3 scripts/tests/test_work_skill_routing_contracts.py を実行します