forcedotcom/sf-skills / plugins/builder/service-omni/skills/service-omni-service-channel-configure
service-omni-service-channel-configure
VerifiedUse to ensure exactly one ServiceChannel exists on a Salesforce org for a routable sObject (Case | Incident | MessagingSession | VoiceCall), reusing any standard or custom channel already bound to that sObject and only deploying a canonical template when none exists. Salesforce enforces one ServiceChannel per RelatedEntity, so the skill detects via the Tooling API first. Standard channels ship for Case (Cases), MessagingSession (sfdc_livemessage), VoiceCall (sfdc_phone); Incident has none. Triggers: configure ServiceChannel for Case/Incident/Messaging/Voice routing, add Incident or Voice routing to Omni. Do not use to tune per-sObject capacity (use PresenceUserConfig.Capacity), to reset a mis-configured channel to canonical shape, or for sObjects outside Case/Incident/MessagingSession/VoiceCall.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 6.3 KB |
| assets/force-app/main/default/serviceChannels/Cases.serviceChannel-meta.xml | config | 407 B |
| assets/force-app/main/default/serviceChannels/Incidents.serviceChannel-meta.xml | config | 415 B |
| assets/force-app/main/default/serviceChannels/MessagingSessions.serviceChannel-meta.xml | config | 431 B |
| assets/force-app/main/default/serviceChannels/VoiceCalls.serviceChannel-meta.xml | config | 418 B |
| assets/package.xml | config | 350 B |
| assets/sfdx-project.json | config | 246 B |
| references/api-notes.md | markdown | 6.0 KB |
| scripts/deploy-and-report.shexecutable | script | 14.6 KB |
references/api-notes.md
View on GitHub# ServiceChannel — API notes
Load this reference only when the deploy fails or Salesforce reports unexpected state. Under normal operation the skill's deploy-and-report script just runs and emits its JSON; this doc is for troubleshooting and extensions.
**Metadata type:** `ServiceChannel` (queryable via the Tooling API for basic fields; Metadata-only for `capacityModel` and other tuning fields). **API version:** v66.
---
## The six fields in the shipped Cases XML
| Field | Value | Semantics |
|---|---|---|
| `capacityModel` | `TAB_BASED` | Capacity accounting model. `TAB_BASED` = each open Console tab = 1 unit of an agent's total capacity. Alternative: `STATUS_BASED` (capacity varies by presence status) |
| `doesMinimizeWidgetOnAccept` | `false` | Whether the Omni widget minimizes when an agent accepts work. `false` = widget stays visible |
| `hasAutoAcceptEnabled` | `false` | Whether work is auto-accepted (no click). `false` = agent must manually accept |
| `isInterruptible` | `false` | Whether new work can interrupt an active work item. `false` = agents finish current work first |
| `label` | `Cases` | UI display name. Must be `Cases` for the standard Case channel |
| `relatedEntityType` | `Case` | The sObject type this channel routes. Must be `Case` for Case routing |
**Fields not in the shipped XML (Salesforce uses defaults):**
- `secondaryRoutingPriorityField` — set only when secondary priority sorting is needed.
- `customEventChannel` / `customEventPayloadField` — only for custom-event-driven channels.
- `dispatcherClass` — only for advanced routing customization.
Fork the skill's XML to set any of these.
## Capacity is not tunable at the channel level on v66
Per-item weighted capacity (`capacityWeight` on older API versions) is no longer a ServiceChannel field on v66; the schema exposes `capacityModel` (`TAB_BASED` | `STATUS_BASED`) instead. For per-agent totals use `PresenceUserConfig.Capacity` at the agent level, or switch `capacityModel` to `STATUS_BASED` for status-dependent behavior. Related renames on v66: `masterLabel` → `label`, `relatedEntity` → `relatedEntityType`; `isCustomerVisible` was removed (customer visibility is now inferred from channel type).
**Implication for this skill:** on a fresh v66 CDO the `Cases` channel already has all six fields at their defaults, so this skill's deploy usually returns `state: Unchanged` / `status: reused`. It is most useful for recovering a mis-configured `Cases` channel, migrating from an older API version's config, or documenting the canonical v66 state in a git-controlled asset. It cannot change per-Case weighted capacity, and enabling auto-accept or minimizing behavior requires forking the XML.
---
## Standard channels' DeveloperNames
Salesforce ships several standard ServiceChannels on Service Cloud orgs:
| DeveloperName | MasterLabel | RelatedEntity | Purpose |
|---|---|---|---|
| `Cases` | `Cases` | `Case` | Standard Case routing (**this skill's target**) |
| `sfdc_liveagent` | `Chat` | `LiveChatTranscript` | Live Agent chat |
| `sfdc_livemessage` | `Messaging` | `MessagingSession` | Messaging (WhatsApp, SMS, etc.) |
| `sfdc_phone` | `Phone` | `VoiceCall` | Voice/telephony |
The standard Case channel's DeveloperName is `Cases` (plural), not `Case` (singular). To configure a different standard channel, fork this skill's XML and package.xml so the file path and package member both match the target DeveloperName.
---
## ServiceChannel's Metadata field is not Tooling-SOQL queryable
`capacityModel` and the other tuning fields cannot be read via Tooling SOQL as a pre-check:
```text
SELECT Id, DeveloperName, MasterLabel, CapacityWeight FROM ServiceChannel WHERE DeveloperName='Cases'
-- INVALID_FIELD: No such column 'CapacityWeight' on entity 'ServiceChannel'.
SELECT Id, DeveloperName, MasterLabel, Metadata FROM ServiceChannel WHERE DeveloperName='Cases'
-- INVALID_FIELD: No such column 'Metadata' on entity 'ServiceChannel'.
```
`GET /services/data/vXX.0/tooling/sobjects/ServiceChannel/<id>` also returns `{Metadata: null}` even when the metadata exists. The workaround is a Metadata API retrieve (`sf project retrieve start --metadata "ServiceChannel:Cases"`) — slow (~90 sec) but reliable. This skill avoids the retrieve entirely by relying on the deploy's own `files[0].state` signal.
Behavior is entity-specific: `WorkSkillRouting` exposes a queryable `Metadata` field, `ServiceChannel` does not. Always describe first (or test with a small query) before assuming Tooling SOQL is a viable read path.
---
## Deploy failure modes
| Symptom | Root cause | Skill behavior |
|---|---|---|
| `INVALID_TYPE` for ServiceChannel | OmniChannelSettings not enabled (`enableOmniChannel=false`) | Translates to: "OmniChannelSettings is not enabled on this org. Run service-omni-base-settings-configure first." |
| `FIELD_INTEGRITY_EXCEPTION` for relatedEntity | Attempted to change `relatedEntity` (immutable on the standard Case channel) | Block; do not change relatedEntity via this skill — write a separate custom-channel-create skill |
| `DUPLICATE_DEVELOPER_NAME` | Tried to create a channel with an existing DeveloperName | Should not happen (this skill updates the existing `Cases`, not creates) — indicates a bug or org corruption |
| `state: Unchanged` | Payload matched existing state | Success — `status: reused` |
| `state: Changed, success: true` | Payload modified state | Success — `status: created` |
---
## Alternative approaches (evaluated, not chosen)
- **Tooling API PATCH on `Metadata`** — fails at the read step (see above), so a PATCH cannot be validated. The Metadata API is the reliable canonical path.
- **Retrieve → parse XML → decide → deploy** — rejected because the ~90-second retrieve latency is not justified when the deploy's own `state: Unchanged` signal is authoritative. If before-state visibility becomes important, add an optional `--with-detect` flag.
- **`sf api request rest` GET → PATCH** — the GET works but returns `Metadata: null` for ServiceChannel, so it is not a viable read path.
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 |