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 sf CLI (My Domain URL, not .lightning.force.com), Service Cloud license present, sf CLI ≥ 2.139.6.
• Production guardrail: the writer computes safe_to_write as IsSandbox OR TrialExpirationDate != null OR OrganizationType in {Developer Edition, Base Edition}, and blocks with no override when it is false. This permits CDOs (IsSandbox=false with a non-null TrialExpirationDate); do not weaken it to a bare IsSandbox check.

Run

configure-and-report.sh is the canonical entry point:

• run — probe; if all five are already enabled, emit reused (no deploy); otherwise run the safe_to_write guard, deploy the explicit assets/force-app/main/default/settings/OmniChannel.settings-meta.xml source file with all five true (a SucceededPartial is treated as failure), re-probe, and emit configured iff all five are now true, else blocked. The explicit source path bypasses source-tracking no-op decisions when the org value has drifted.
• plan — probe only; emit reused if all enabled, else action_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 was SucceededPartial, 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 — other Settings types belong to platform-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