service-omni-service-channel-configure

# service-omni-service-channel-configure Ensure exactly one `ServiceChannel` is present for a routable sObject, reusing whatever is already bound (Salesforce standard or a pre-existing custom channel) and deploying the skill's canonical v66 template only when none exists. Salesforce enforces one ServiceChannel per `RelatedEntity`, so the skill detects first and never deploys blindly — deploying a second channel for an sObject that already has one fails with "This Salesforce object is already in use by another Service channel." It handles one sObject per call; callers configuring multiple sObjects invoke it once for each sObject, after `service-omni-base-settings-configure` has enabled Omni-Channel. | sObject | Standard channel (if any) | Canonical asset | |---|---|---| | `Case` | `Cases` | `Cases.serviceChannel-meta.xml` | | `Incident` | none (Incident Management sObject) | `Incidents.serviceChannel-meta.xml` — deployed on first run | | `MessagingSession` | `sfdc_livemessage` | `MessagingSessions.serviceChannel-meta.xml` — deployed only if the standard channel is missing | | `VoiceCall` | `sfdc_phone` | `VoiceCalls.serviceChannel-meta.xml` — deployed only if the standard channel is missing | ## Inputs ```bash bash scripts/deploy-and-report.sh <org-alias> [Case|Incident|MessagingSession|VoiceCall] ``` - `org-alias` (required). - `sobject_type` (optional, default `Case`) — one of `Case | Incident | MessagingSession | VoiceCall`. ## Preconditions and safety - Target org authenticated via `sf` CLI (My Domain URL), Service Cloud license, `sf` CLI ≥ 2.139.6. - Omni-Channel base settings enabled (`service-omni-base-settings-configure`) — `ServiceChannel` is only queryable/writable when `enableOmniChannel=true`; a `INVALID_TYPE` on deploy means base settings are off. - `Incident` requires the Incident Management feature enabled; `MessagingSession` requires Enhanced Messaging. The skill verifies `EntityDefinition` first and blocks with a click-path when the target sObject is absent. ## Run `deploy-and-report.sh` performs the prereq check, discovery, and (only when needed) deploy, then emits the report: 1. **Prereq** — confirm the target sObject is queryable via `EntityDefinition`; block with a click-path otherwise. 2. **Discover** — query the Tooling API for a `ServiceChannel` with `RelatedEntity = <sobject_type>`. `ServiceChannel` is a Tooling entity on v66; the standard Data API returns `INVALID_TYPE`. A hit means reuse. 3. **Deploy** (only when nothing was found) — `sf project deploy start` of the canonical XML (`Cases` | `Incidents` | `MessagingSessions` | `VoiceCalls`); a `Changed` state is `created`, `Unchanged` is `reused`. ## Behavior **Detect-then-reuse-or-deploy.** Because Salesforce rejects a second channel per `RelatedEntity`, deploy-first is unsafe: an operator who renamed the standard `Cases` channel would hit the "already in use" error instead of gracefully reusing. Tooling discovery is fast and returns both the reuse decision and the discovered `DeveloperName` in one call. The trade-off is that the skill cannot tell "our canonical shape matches" from "some custom channel is bound" — an operator with a non-canonical channel gets `reused` and their channel is left untouched (v1 never overwrites operator state). **Capacity model.** The canonical assets use `TAB_BASED` for every variant. `STATUS_BASED` requires companion fields whose full schema is undocumented, so it is out of scope; per-agent capacity tuning belongs to `PresenceUserConfig.Capacity`, not this skill. **Concurrency.** If a deploy fails with "already in use," another process created the channel between discovery and deploy; the skill soft-fails and a re-run reuses it. ## Output contract A single JSON object per invocation with `status` ∈ `created` | `reused` | `blocked`, plus `sobject_type`, `channel_developer_name`, `channel_id`, `channel_origin`, `target_capacity_model`, `target_related_entity_type`, `before_state`, `deploy_id`, `manual_actions`, and `blocking_issue`. - `reused` — an existing channel was found (discovery hit, or a deploy returned `Unchanged`). - `created` — no channel existed; the canonical XML deployed with `Changed`. - `blocked` — the sObject is not on the org, base settings are off (`INVALID_TYPE`), or a race left the channel already in use. - `channel_origin` is one of `salesforce_standard` (an `sfdc_*` name or `Cases`), `canonical_asset` (a shipped asset name), `canonical_template` (freshly deployed this run), or `custom` (a pre-existing org-specific channel). - `channel_id` is populated whenever a channel exists (`null` on `blocked`); `deploy_id` is populated only on the deploy branch; `blocking_issue` is non-null only when `status: blocked`. ## Limitations - One sObject per invocation. - Only `Case`, `Incident`, `MessagingSession`, `VoiceCall` are supported — extend by adding an `assets/force-app/main/default/serviceChannels/<Name>.serviceChannel-meta.xml` file and a dispatcher branch. - Always reuses an existing channel; it does not reset a mis-configured channel to canonical shape. ## References | File | When to read | |---|---| | `references/api-notes.md` | On unexpected discovery results, deploy failures, or sObject-specific schema questions |