service-omni-base-settings-configure
Use to enable the five Omni-Channel base settings on a Salesforce org via the Metadata API. The canonical writer scripts/configure-and-report.sh detects, deploys, and re-verifies in one call (run mode) or detects only (plan mode); it is idempotent (deploys only when a toggle is false or missing) and guards writes with a sandbox/CDO/trial/DE safe_to_write check. It always surfaces the UI-only login-behavior gap in its report. Triggers: enable Omni-Channel, turn on Omni base settings, configure OmniChannelSettings, deploy Settings:OmniChannel. Do not use to configure downstream Omni entities (queues, presence, permissions — use the entity-specific skill) or to deploy other Settings types (use platform-metadata-deploy).
How do I install this agent skill?
npx skills add https://github.com/forcedotcom/sf-skills --skill service-omni-base-settings-configureIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill is a standard Salesforce configuration utility designed to enable Omni-Channel settings. It includes robust security practices such as a production environment guardrail and specific parsing logic for external data.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
service-omni-base-settings-configure
Enable the five OmniChannelSettings booleans (enableOmniChannel, enableOmniAutoLoginPrompt, enableOmniSecondaryRoutingPriority, enableOmniSkillsRouting, enableOmniStatusCapModel) via a single Metadata API deploy. Nothing downstream — queues, presence statuses, routing flows — works without enableOmniChannel=true, so this must be the first write in an Omni setup sequence. The skill probes first and deploys only when a toggle is false or missing.
Inputs
bash scripts/configure-and-report.sh run <org-alias> # detect; deploy if needed; re-verify
bash scripts/configure-and-report.sh plan <org-alias> # read-only: detect only, never deploys
org-alias is the only input. All five toggles are always set to true — the skill takes no per-toggle overrides; a caller who wants a subset should use platform-metadata-deploy with their own OmniChannel.settings-meta.xml.
Preconditions and safety
- Target org authenticated via
sfCLI (My Domain URL, not.lightning.force.com), Service Cloud license present,sfCLI ≥ 2.139.6. - Production guardrail: the writer computes
safe_to_writeasIsSandboxORTrialExpirationDate != nullOROrganizationTypein {Developer Edition, Base Edition}, and blocks with no override when it is false. This permits CDOs (IsSandbox=falsewith a non-nullTrialExpirationDate); do not weaken it to a bareIsSandboxcheck.
Run
configure-and-report.sh is the canonical entry point:
- run — probe; if all five are already enabled, emit
reused(no deploy); otherwise run thesafe_to_writeguard, deploy the explicitassets/force-app/main/default/settings/OmniChannel.settings-meta.xmlsource file with all fivetrue(aSucceededPartialis treated as failure), re-probe, and emitconfigurediff all five are now true, elseblocked. The explicit source path bypasses source-tracking no-op decisions when the org value has drifted. - plan — probe only; emit
reusedif all enabled, elseaction_needed. Never deploys.
The probe retrieves Settings:OmniChannel and takes 1–2 minutes (Metadata retrieve is slow); this is expected. The deploy runs from assets/ (a valid DX project) and names the settings file with --source-dir; its template is never mutated at runtime, so the skill stays reproducible and does not report "No local changes to deploy" solely because local source tracking is clean.
Behavior
Whole-document writes. Settings is a whole-document metadata type — the Metadata API does not accept partial updates, so the skill always deploys the full file rather than PATCHing individual toggles.
Login-behavior gap. The Omni login-behavior radio (Setup → Omni-Channel Settings → "Define login behavior when an agent opens a new window/tab") has no public API on v66. The report always surfaces its click-path — even on a no-op reused run — so a "nothing to do" result never hides the one manual action. enableOmniAutoLoginPrompt still deploys cleanly (other Omni features may depend on it internally) but does not drive that radio.
Fail-closed verify. After a deploy the skill re-probes and requires all five toggles true; a deploy that reports success but does not stick (an uncommon org-level restriction) blocks rather than reporting success.
Output contract
configure-and-report.sh emits a single JSON object with status ∈ configured | reused | action_needed | blocked, a top-level all_enabled boolean the coordinator reads to gate downstream skills, full before/after toggle objects, deploy_id, safe_to_write, manual_actions, and blocking_issue.
configured— a toggle was false, the deploy ran, and the re-probe shows all true (run mode).reused— all five were already true; no deploy.action_needed— plan mode saw a disabled toggle; nothing deployed.blocked—safe_to_write=false, the deploy failed or wasSucceededPartial, or the re-probe still shows a false toggle.
manual_actions always includes the login-behavior gap entry on non-blocked reports; deploy_id is null for reused/action_needed; blocking_issue names the failure only when status: blocked.
Limitations
- Configures only
OmniChannelSettings, always with all five toggles true — otherSettingstypes belong toplatform-metadata-deploy. - Cannot turn the login-behavior radio (no public API on v66) — it only surfaces the click-path.
References
| File | When to read |
|---|---|
references/api-notes.md | Before a deploy — the five toggles' semantics, dependencies, and the login-behavior caveat |
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/forcedotcom/sf-skills/service-omni-base-settings-configure">View service-omni-base-settings-configure on skillZs</a>