@salesforce/afv-skills 1.46.0 → 1.48.0

package/skills/service-omni-queue-deploy/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: service-omni-queue-deploy
+description: "Use to verify or create a Queue on a Salesforce org for a routable sObject (Case | Incident | MessagingSession | VoiceCall), discovered via its QueueSobject binding rather than by hardcoded name. Reuses whatever queue already routes the target sObject; with --create-if-missing it creates a Queue via the Metadata API (Group + QueueSobject) when none is bound and aligns its QueueRoutingConfigId to a caller-specified QRC. Returns created, reused, updated, or blocked. Triggers: verify or create a queue for Case/Incident/Messaging/Voice routing, align queue routing config, set up an Omni voice queue. Do not use to add users to the queue (service-omni-queue-members-assign) or for sObjects outside Case/Incident/MessagingSession/VoiceCall."
+allowed-tools: Bash Read Write Edit Glob Grep
+metadata:
+  version: "1.0"
+  domains: ["Service"]
+  minApiVersion: "66.0"
+  relatedSkills:
+    - "service-omni-channel-setup-coordinate"
+    - "service-omni-queue-members-assign"
+    - "service-omni-queue-routing-config-deploy"
+  accessCheck:
+    - type: license
+      value: ServiceCloud
+  cliTools:
+    - tool: ["jq"]
+      semver: ">=1.6"
+    - tool: ["sf"]
+      semver: ">=2.139.6"
+---
+
+# service-omni-queue-deploy
+
+Verify that a `Group` (Type='Queue') exists with a `QueueSobject` binding to the requested routable sObject, reusing whatever is already there. With `--create-if-missing`, create the queue via the Metadata API (Group + QueueSobject) when none is bound, and optionally align its `QueueRoutingConfigId` to a caller-specified QRC. The skill discovers the queue by its `QueueSobject.SobjectType` binding, not by name, because real orgs name queues inconsistently (`CaseQueue`, `messagingqueue`, `Omni_Demo_Cases_Queue`) — the functional link between a queue and the routing it supports is the binding, not the `DeveloperName`. It is invoked by `service-omni-channel-setup-coordinate`; queue membership is a separate leaf (`service-omni-queue-members-assign`) and the QRC it aligns to comes from `service-omni-queue-routing-config-deploy`.
+
+## Inputs
+
+```bash
+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` (required).
+- `sobject_type` (optional, default `Case`).
+- `routing_config_dn` (optional) — when passed, forces alignment to that QRC; when omitted for Case it defaults to `Case_Routing_Config`; when omitted for other sObjects the skill reports the existing binding without forcing.
+- `queue_developer_name` (optional 4th positional) — the explicit queue to operate on, or the name to create with `--create-if-missing`.
+- `--create-if-missing` (flag, or `QUEUE_CREATE_IF_MISSING=1`) — create the queue via the Metadata API when none is bound; label defaults to a spaced form of the DeveloperName (override via `QUEUE_LABEL`).
+
+## Preconditions and safety
+
+- Target org authenticated via `sf` CLI (My Domain URL), Service Cloud license, `sf` CLI ≥ 2.139.6.
+- The target sObject is enabled on the org — verified via `EntityDefinition` before any write; missing sObjects block with a feature-enablement click-path (Incident Management for Incident, Enhanced Messaging for MessagingSession).
+- When `routing_config_dn` is supplied, that QRC must already exist (resolved by DeveloperName); otherwise the run blocks with a pointer to `service-omni-queue-routing-config-deploy`.
+- The three-way `safe_to_write` production guard applies.
+
+## Run
+
+`verify-and-align.sh` runs the full sequence and emits the report:
+
+1. **Prereq** — confirm the sObject via `EntityDefinition`.
+2. **Discover** — `QueueSobject WHERE SobjectType = '<sobject_type>'`. A hit is reused. No hit: create via the Metadata API when `--create-if-missing`, else block with a Setup click-path.
+3. **Inspect** — read the queue's `QueueRoutingConfigId` and its full `QueueSobject` list.
+4. **Align (optional)** — when `routing_config_dn` is supplied, resolve its Id and PATCH `Group.QueueRoutingConfigId` if drifted.
+5. **Re-query** — confirm convergence and emit JSON.
+
+## Behavior
+
+**Discovery over naming.** Any queue whose `QueueSobject` routes the target sObject is *the* queue for that sObject, regardless of its name. A name-based check would miss a queue like `messagingqueue` and either block or create a duplicate.
+
+**Creation is idempotent.** Metadata deploy upserts by fullName, so `--create-if-missing` adopts/updates an existing same-named queue rather than making a second one. Creation ships the minimal safe set (`doesSendEmailToMembers=false` plus the sObject binding) and never deletes existing `QueueSobject` rows — other sObjects may be intentionally routed through the same queue.
+
+**Forced vs discovered QRC.** For Case, the coordinator wants deterministic alignment to `Case_Routing_Config`, so the skill forces it. For other sObjects with no coordinator-owned QRC, the skill reports whatever the queue is already bound to (`source: discovered`) rather than forcing a name that may not exist. QRC Ids are resolved by `DeveloperName` at runtime — never hardcoded.
+
+**Ambiguity.** If multiple distinct queues bind the same sObject, the skill does not guess — it blocks and asks the operator to disambiguate, unless a canonical name matches or an explicit `queue_developer_name` pins the exact queue.
+
+**PATCH hygiene.** `sf api request rest` prints a beta warning on stderr; the skill captures stderr separately so it cannot corrupt JSON parsing, and it preserves the queue Id on PATCH (never delete + recreate) because downstream references point to it.
+
+## Output contract
+
+A single JSON object with `status` ∈ `created` | `reused` | `updated` | `blocked`, plus `sobject_type`, `developer_name`, `queue_created`, `id`, `queue_routing_config_id`, `queue_routing_config_developer_name`, `queue_routing_config_source` (`forced` | `discovered`), `queue_sobjects`, a `before` snapshot, `manual_actions`, and `blocking_issue`.
+
+- `created` — no queue was bound and `--create-if-missing` created one (binding its QRC when supplied).
+- `reused` — a bound queue existed and, if a QRC was passed, already matched (no PATCH).
+- `updated` — a bound queue existed but the caller-supplied QRC was drifted; PATCH ran.
+- `blocked` — sObject absent, no bound queue and no `--create-if-missing`, supplied QRC missing, or the re-query showed state did not converge.
+
+`queue_created` is `true` only when this run deployed a new queue; `blocking_issue` names the specific precondition that failed and `manual_actions` carries the click-path.
+
+## Limitations
+
+- Only `Case`, `Incident`, `MessagingSession`, `VoiceCall` — extend by adding a dispatcher branch.
+- Never deletes a queue or its `QueueSobject` rows, and never modifies queue members.
+- Creation ships a minimal queue shape; exotic fields (`doesIncludeBosses`, email routing address) are not set.
+
+## References
+
+| File | When to read |
+|---|---|
+| `references/api-notes.md` | On a block for a missing queue (manual click-path) or unexpected Data API errors — Queue/QueueSobject schema, the Metadata API creation shape, and the stderr-separation and queue-naming-variance notes |

package/skills/service-omni-queue-deploy/references/api-notes.md

@@ -0,0 +1,140 @@
+# Queue — API notes
+
+Load this reference when the skill blocks on a queue it cannot safely create or align (needs the manual click-path) or on unexpected errors.
+
+**sObject type:** `Group` with `Type='Queue'`. Queues in Salesforce are a special kind of Group.
+**Child records:** `QueueSobject` (many-to-one to Group; links queue to which sObject types it can hold).
+**Optional membership:** `GroupMember` records (many-to-one to Group; users in the queue). See `service-omni-queue-members-assign` — this skill does NOT touch members.
+**API version verified:** v66 (Summer '26 baseline).
+
+---
+
+## Schema (fields we use)
+
+### `Group` (queue-typed subset)
+
+| Field | Type | Semantics |
+|---|---|---|
+| `Id` | Id | Primary key. 18 chars starting with `00G` |
+| `Name` | string(40) | UI display name |
+| `DeveloperName` | string(80) | Unique per-org API name. Used for cross-org idempotency |
+| `Type` | picklist | Must be `Queue` (other values: `Role`, `RoleAndSubordinates`, `Territory`, etc. — this skill filters to Queue only) |
+| `QueueRoutingConfigId` | Id | FK to `QueueRoutingConfig`. Null-able but required for Omni routing |
+
+Note: PATCHing `Type` on an existing Group is not allowed — Salesforce rejects it. Type is set at creation.
+
+### `QueueSobject`
+
+| Field | Type | Semantics |
+|---|---|---|
+| `Id` | Id | Primary key. 18 chars starting with `03g` |
+| `QueueId` | Id | FK to `Group.Id`. Must be a Queue-typed Group |
+| `SobjectType` | string | e.g., `Case`, `Lead`, `ContactRequest`. One record per sObject type the queue can hold |
+
+Notes:
+- QueueSobject is create-only via Data API — Salesforce does not allow PATCH on any QueueSobject field
+- To change which sObject types a queue holds: DELETE the unwanted QueueSobject + POST new ones (destructive)
+- v1 skill ONLY POSTS missing QueueSobject records; never deletes existing ones (preserves other-team routing decisions)
+
+---
+
+## Data API operations
+
+### Query queue by DeveloperName
+
+```text
+SELECT Id, DeveloperName, Type, QueueRoutingConfigId FROM Group WHERE DeveloperName='CaseQueue' AND Type='Queue'
+```
+
+Always include `AND Type='Queue'` — DeveloperName is unique across ALL Group types, but the filter guards against non-Queue Groups with the same DeveloperName in edge cases.
+
+### Query QueueSobject for a queue
+
+```text
+SELECT SobjectType FROM QueueSobject WHERE QueueId='<queue-id>'
+```
+
+Returns array of sObject-type strings. Use `.index(target)` to check if target sObject type is present.
+
+### PATCH routing config
+
+```text
+PATCH /services/data/v66.0/sobjects/Group/<queue-id>
+{"QueueRoutingConfigId": "<new-routing-config-id>"}
+```
+
+Response: empty body (HTTP 204) on success. Errors: `INVALID_FIELD_VALUE` if the target Id doesn't exist or isn't a QueueRoutingConfig, `INSUFFICIENT_ACCESS` if user lacks perm.
+
+### POST QueueSobject
+
+```text
+POST /services/data/v66.0/sobjects/QueueSobject
+{"QueueId": "<queue-id>", "SobjectType": "Case"}
+```
+
+Response: `{"id":"03g...","success":true,"errors":[]}` (HTTP 201).
+
+---
+
+## Queue creation via the Metadata API
+
+By default the skill verifies and aligns an existing queue. With `--create-if-missing` it creates one via the Metadata API using a `.queue-meta.xml` file, which upserts by fullName (so re-running adopts an existing same-named queue rather than duplicating it).
+
+Notes on the moving parts:
+- The `Group` record (`Type='Queue'`) and its `QueueSobject` binding are both what the creation ships.
+- Behavioral flags like `doesIncludeBosses` exist only via the Metadata API (the Data API cannot set them); the creation ships the minimal safe set (`doesSendEmailToMembers=false` plus the sObject binding).
+- Members are deliberately not touched here. Deploying `<queueMembers>` would replace existing members (destructive), so membership is left to `service-omni-queue-members-assign`, which adds `GroupMember` rows additively.
+
+Creation never deletes existing `QueueSobject` rows — other sObjects may be intentionally routed through the same queue.
+
+---
+
+## Manual click-path (when Queue doesn't exist)
+
+Setup UI:
+
+1. **Setup → Feature Settings → Service → Queues → New**
+2. **Label:** `CaseQueue`
+3. **Name (DeveloperName):** `CaseQueue`
+4. **Routing Configuration:** `Case_Routing_Config` (must exist first — see [service-omni-queue-routing-config-deploy](../../service-omni-queue-routing-config-deploy/))
+5. **Send Email to Members:** unchecked (v1 default)
+6. **Supported Objects:** move `Case` to Selected
+7. **Queue Members:** leave empty (`service-omni-queue-members-assign` handles this)
+8. **Save**
+9. Re-run this skill — should return `status: reused`
+
+Metadata API alternative (advanced):
+
+```bash
+mkdir -p /tmp/q-create/force-app/main/default/queues
+cat > /tmp/q-create/sfdx-project.json <<'EOF'
+{"packageDirectories":[{"path":"force-app","default":true}],"sourceApiVersion":"66.0"}
+EOF
+cat > /tmp/q-create/force-app/main/default/queues/CaseQueue.queue-meta.xml <<'EOF'
+<?xml version="1.0" encoding="UTF-8"?>
+<Queue xmlns="http://soap.sforce.com/2006/04/metadata">
+    <doesIncludeBosses>false</doesIncludeBosses>
+    <doesSendEmailToMembers>false</doesSendEmailToMembers>
+    <name>CaseQueue</name>
+    <queueRoutingConfig>Case_Routing_Config</queueRoutingConfig>
+    <queueSobject>
+        <sobjectType>Case</sobjectType>
+    </queueSobject>
+</Queue>
+EOF
+cd /tmp/q-create && sf project deploy start --target-org <alias> --metadata "Queue:CaseQueue"
+```text
+
+**Warning:** if `CaseQueue` already exists on the org, this Metadata API deploy will REPLACE `queueMembers` with an empty list (destructive). Do NOT run this on a queue that has existing members you want to keep. This is why v1 verify-only defers create.
+
+---
+
+## Failure modes
+
+| Symptom | Root cause | Skill behavior |
+|---|---|---|
+| SOQL query returns 0 rows for `Group WHERE DeveloperName='CaseQueue' AND Type='Queue'` and the queue cannot be created safely | Queue doesn't exist | Block with click-path (see above) |
+| SOQL query returns 0 rows for `QueueRoutingConfig WHERE DeveloperName='Case_Routing_Config'` | Prereq skill not run | Block: "Run service-omni-queue-routing-config-deploy first" |
+| PATCH `Group.QueueRoutingConfigId` returns `INVALID_FIELD_VALUE` | Target routing config Id doesn't exist or isn't a QueueRoutingConfig | Block: inconsistent state between the two SOQL queries; retry the skill |
+| POST `QueueSobject` returns `DUPLICATE_VALUE` | Race with concurrent skill run; sObject already added | Not a failure — re-query will confirm the record exists |
+| PATCH returns `INSUFFICIENT_ACCESS_OR_READONLY` | Executing user lacks perm | Block: escalate to a System Administrator |