forcedotcom/sf-skills / plugins/builder/service-omni/skills/service-omni-queue-routing-config-deploy
service-omni-queue-routing-config-deploy
VerifiedUse to create or update a QueueRoutingConfig record on a Salesforce org via the Data API (idempotent SOQL detect + REST upsert). Naming is target-derived: Case→Case_Routing_Config, VoiceCall→Voice_Routing_Config, Incident→Incident_Routing_Config, MessagingSession→Messaging_Routing_Config (via QRC_ROUTING_TARGET), or pass an explicit developer-name/label/capacity/priority. RoutingModel MostAvailable (default) or LeastActive. Triggers: create a Case or Voice routing config, deploy a QueueRoutingConfig, set up queue routing for Omni Cases/Voice, configure CapacityWeight per queue. Do not use for attribute-based routing (IsAttributeBased=true is out of scope) or routing models other than MostAvailable/LeastActive.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.4 KB |
| references/api-notes.md | markdown | 6.5 KB |
| scripts/tests/_bootstrap.py | script | 4.1 KB |
| scripts/tests/test_queue_routing_config_contracts.pyexecutable | script | 2.9 KB |
| scripts/upsert-and-report.shexecutable | script | 25.0 KB |
references/api-notes.md
View on GitHub# QueueRoutingConfig — API notes
Load this reference **only when the skill hits an unexpected error or when customizing fields**. The happy path is straightforward and doesn't need this doc.
**sObject type:** `QueueRoutingConfig` (first-class, SOQL-queryable via the Data API). **API version:** v66.
---
## Schema (fields we use)
| Field | Type | v1 default | Semantics |
|---|---|---|---|
| `Id` | Id | (auto-generated) | Primary key |
| `DeveloperName` | string(80) | `Case_Routing_Config` | Unique per-org identifier; used for idempotent detection |
| `MasterLabel` | string(80) | `Case Routing Config` | UI display name |
| `RoutingModel` | picklist | `MostAvailable` | See RoutingModel Semantics below |
| `RoutingPriority` | integer | `1` | **REQUIRED, non-nillable** (confirmed via `sf sobject describe`). Omitting it makes every POST fail with `REQUIRED_FIELD_MISSING`. `1` = highest priority |
| `IsAttributeBased` | boolean | `false` | Whether to use attribute-based routing (v1 does not — requires attribute definitions) |
| `CapacityWeight` | integer(1..10) | `5` | How much of an agent's capacity ONE work item from this queue consumes. See CapacityWeight interaction below |
| `PushTimeout` | integer (sec) | `null` | Seconds to wait before pushing work back to queue if agent doesn't accept. `null` = use Omni default of 30 sec |
| `OverflowAssigneeId` | User Id | `null` | Fallback User that work is assigned to when all queue members are unavailable. `null` = no overflow (work stays queued indefinitely). Settable via the skill's `overflow-assignee` input (`QRC_OVERFLOW_ASSIGNEE`) — a Username or `005` Id resolved to an **active** User before the write; omitting it preserves the existing value rather than clearing it |
## RoutingModel semantics
| Value | Behavior |
|---|---|
| `MostAvailable` | Route to the agent with the most remaining capacity (i.e., handling the fewest current work items) |
| `LeastActive` | Route to the agent whose last work-item interaction was longest ago (load-balancing over time) |
**Not supported on v66:** `Priority` (removed), `SkillsBased` (moved to WorkSkillRouting on v66).
For most Omni Case setups, `MostAvailable` is the right default — it maximizes queue throughput. `LeastActive` is useful when you want to keep all agents equally busy over time (e.g., to prevent burnout of high-performers).
## CapacityWeight interaction with agent capacity
Capacity in Omni-Channel v66 is a three-way math:
- **Agent total capacity:** `PresenceUserConfig.Capacity` (default 10) — how much total work an agent can hold at once
- **Per-queue weight:** `QueueRoutingConfig.CapacityWeight` (this skill's default 5) — how much a single work item from this queue consumes
- **Per-channel weight:** removed on v66 — used to be `ServiceChannel.CapacityWeight`; no longer configurable
**Concrete example:**
- Agent with `PresenceUserConfig.Capacity=10`
- Case routes through `Case_Routing_Config` with `CapacityWeight=5`
- Agent can hold `10 / 5 = 2` cases simultaneously
- If a third case comes in, it stays queued until the agent completes one
**Rules of thumb:**
- Weight = 1 → agent holds 10 cases at once (high-throughput but hard to focus)
- Weight = 5 → agent holds 2 cases at once (this skill's default — balanced)
- Weight = 10 → agent holds 1 case at a time (deep focus, low throughput)
---
## Data API endpoints used
**GET (query):**
```text
GET /services/data/v66.0/query?q=SELECT+Id,+DeveloperName,+MasterLabel,+RoutingModel,+IsAttributeBased,+CapacityWeight,+PushTimeout,+OverflowAssigneeId+FROM+QueueRoutingConfig+WHERE+DeveloperName='Case_Routing_Config'
```
Or equivalently via `sf data query --query "SELECT ... FROM QueueRoutingConfig WHERE ..."` (which is what the skill's script uses).
**POST (create):**
```text
POST /services/data/v66.0/sobjects/QueueRoutingConfig
Content-Type: application/json
{
"DeveloperName": "Case_Routing_Config",
"MasterLabel": "Case Routing Config",
"RoutingModel": "MostAvailable",
"RoutingPriority": 1,
"CapacityWeight": 5,
"IsAttributeBased": false
}
```
Response: `{"id":"0K9RZ...", "success":true, "errors":[]}` (HTTP 201).
`RoutingPriority` is REQUIRED — a POST without it fails with `REQUIRED_FIELD_MISSING`.
**PATCH (update):**
```text
PATCH /services/data/v66.0/sobjects/QueueRoutingConfig/<id>
Content-Type: application/json
{
"MasterLabel": "Case Routing Config",
"RoutingModel": "MostAvailable",
"RoutingPriority": 1,
"CapacityWeight": 5,
"IsAttributeBased": false
}
```
Response: empty body (HTTP 204). Note that PATCH does NOT include `DeveloperName` — Salesforce doesn't allow renaming via PATCH on QueueRoutingConfig.
Both invoked via `sf api request rest --target-org <alias> <path> --method POST|PATCH --body <json>`.
---
## Failure modes
| Symptom | Root cause | Skill behavior |
|---|---|---|
| Query returns `INVALID_TYPE` for QueueRoutingConfig | OmniChannelSettings not enabled | Skill translates to: `"OmniChannelSettings is not enabled on this org. Run service-omni-base-settings-configure first."` |
| POST returns `DUPLICATE_VALUE` on DeveloperName | Race with concurrent skill run | Retry once — the pre-check will now find the record and PATCH instead |
| POST/PATCH returns `INVALID_FIELD_VALUE` on RoutingModel | Value is not `MostAvailable` or `LeastActive` | Fail with a clear message naming the valid values |
| POST/PATCH returns `INVALID_FIELD_VALUE` on CapacityWeight | Value < 1 or > 10 | Fail with a clear message naming the valid range |
| PATCH silently changes nothing | Field values already match | Not a failure — just means Salesforce detected no diff. Skill correctly reports `status: reused` from its own pre-check |
| POST returns `INSUFFICIENT_ACCESS_OR_READONLY` | Executing user lacks `Manage Public List Views` OR the org has other Omni restrictions | Fail with escalation guidance |
---
## Why Data API instead of Metadata API
QueueRoutingConfig is a first-class sObject on Salesforce (unlike ServiceChannel, whose tuning fields are Metadata-only). The Data API has these advantages here:
- **Speed:** ~1 sec per call vs ~10 sec for Metadata deploy
- **Idempotency:** SOQL query returns clean field values for pre-check comparison; Metadata retrieve is slower and returns XML that needs parsing
- **Reversibility:** PATCH just updates fields; Metadata deploy replaces the whole record
- **No DX project overhead:** no `assets/`, no `sfdx-project.json`, no `package.xml`
Metadata API is still supported (`sf project deploy start --metadata "QueueRoutingConfig:Case_Routing_Config"` works), but adds latency with no functional benefit for this entity.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |