Skip to main content
skill CX Codex

service-omni-queue-deploy — Claude Code skill: what it does

The service-omni-queue-deploy skill verifies or provisions a Salesforce queue for routable objects using QueueSobject bindings. It runs when setting up Omni-Channel routing through an AI agent.

Apache-2.0 116 installs ★ 1,183 updated 2026-10-23

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add forcedotcom/sf-skills --skill service-omni-queue-deploy -a claude-code
Open on GitHub

What service-omni-queue-deploy does

The tool locates an existing Salesforce queue by its binding to objects like Case, Incident, MessagingSession or VoiceCall rather than relying on hardcoded names. When no binding exists, the --create-if-missing flag builds a new queue via the Metadata API along with the target routing configuration. The execution concludes by emitting a structured JSON status indicating whether the queue was created, reused, updated, or blocked.

Operation requires an authenticated Salesforce organization through the sf CLI, a Service Cloud license, and jq version 1.6 or newer. The script checks entity definitions prior to writing and handles routing configuration alignment. Queue membership management and unsupported object types remain outside the scope of this utility.

What it helps with

  • verify queue binding for a Salesforce object
  • provision a missing queue via Metadata API
  • align queue routing configuration
  • generate deployment status JSON report

Example prompts for the agent

  • Verify or create a VoiceCall queue in myorg
  • Set up a Case queue with custom routing config
  • Deploy an Omni-Channel queue with missing creation enabled

How to install service-omni-queue-deploy

1Skills CLI (Vercel)

npx skills add forcedotcom/sf-skills --skill service-omni-queue-deploy -a claude-code

2Manually: put the files in place

~/.claude/skills/service-omni-queue-deploy/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/service-omni-queue-deploy/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about service-omni-queue-deploy

How to install service-omni-queue-deploy in Claude Code?

Run npx skills add forcedotcom/sf-skills --skill service-omni-queue-deploy -a claude-code, then check ~/.claude/skills/service-omni-queue-deploy/SKILL.md.

What does service-omni-queue-deploy do?

It checks for an existing queue via its object binding, reuses it or creates a new one through the Metadata API, and aligns routing configurations.

What is required to run service-omni-queue-deploy?

An authenticated Salesforce org via sf CLI, a Service Cloud license, and jq version 1.6 or higher are required.

Source text

SKILL.md · Apache-2.0
---
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: "OrgPermissions.LightningService"
  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 |

© forcedotcom · Apache-2.0 · forcedotcom/sf-skills

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set232

The whole set →
experience-lwc-widget-migrate The experience-lwc-widget-migrate Claude Code skill turns a named Lightning web component (LWC) into a declarative HXL / Agentforce widget. It runs when a request calls for rebuilding or migrating an existing LWC as a widget. CX Codex +1 126installs education-cloud-academic-calendar-generate education-cloud-academic-calendar-generate builds an Education Cloud academic year with terms and sessions from dates in a prompt or document. Use it when setting up a new academic calendar. CX Codex +1 124installs life-sciences-kam-coordinate life-sciences-kam-coordinate runs the full sequential Life Sciences Cloud configuration workflow for a Key Account Management user. CX Codex +1 123installs education-cloud-course-catalog-migrate education-cloud-course-catalog-migrate is a skill that imports course catalogs from CSV, PDFs, or websites into Education Cloud, creates Learning records, and links lectures to labs. CX Codex +1 117installs service-omni-routing-flow-deploy The service-omni-routing-flow-deploy Claude Code skill deploys an Omni-Channel routing Flow for Case or VoiceCall. It handles requests to route work to a queue or by skill, then checks the result. CX Codex +1 116installs dx-lifecycle-center dx-lifecycle-center — a skill for Claude Code and other platforms that manages Salesforce org connections and deploys metadata. Runs when you request environment setup or component transfers. CX Codex +1 110installs service-omni-queue-routing-config-deploy The service-omni-queue-routing-config-deploy Claude Code skill creates or updates Salesforce Omni-Channel queue routing settings. It runs for Case or Voice queue setup and when deploying a QueueRoutingConfig. CX Codex +1 108installs platform-metadata-discovery-get platform-metadata-discovery-get is a Claude Code skill that checks which Salesforce metadata already exists in an org. It runs before metadata changes or code that refers to org metadata. CX Codex +1 107installs

Project sponsors

Companies that keep this analytics open