/service-omni-channel-setup-coordinate

name: service-omni-channel-setup-coordinate
description: "Use to stand up Omni-Channel setup headlessly on Salesforce: base settings, agent users, service channels, routing configs, queues (create and align) and members, presence statuses, permission assignments, the classic Omni Supervisor config plus its action/tab surface, and — for Case and VoiceCall — the record-triggered routing flow. Supports Case, Incident, MessagingSession, and VoiceCall targets; reuses existing records and creates what is missing. Opt-in extras: presence user config, Omni sidebar, skills-based routing, and field-based WorkSkillRouting; also reports (read-only) whether the org is on the classic supervisor surface or Command Center V2. Triggers: set up Omni-Channel, configure Omni routing, provision Omni agents or supervisors, configure Case/Incident/Messaging/Voice routing. Do not use for Agentforce agents or bots, a single existing Omni field change, bare metadata deployment (use platform-metadata-deploy), or to enable Command Center V2 (not writable via the Metadata API)."
allowed-tools: Bash Read Write Edit Glob Grep AskUserQuestion TodoWrite
metadata:
  version: "1.0"
  domains: ["Service"]
  minApiVersion: "66.0"
  relatedSkills:
    - "platform-metadata-deploy"
    - "service-agentforce-human-escalation-configure"
    - "service-omni-agent-users-create"
    - "service-omni-base-settings-configure"
    - "service-omni-command-center-analyze"
    - "service-omni-permission-set-assign"
    - "service-omni-presence-status-deploy"
    - "service-omni-presence-user-config-deploy"
    - "service-omni-queue-deploy"
    - "service-omni-queue-members-assign"
    - "service-omni-queue-routing-config-deploy"
    - "service-omni-routing-flow-deploy"
    - "service-omni-service-channel-configure"
    - "service-omni-sidebar-configure"
    - "service-omni-skills-based-routing-configure"
    - "service-omni-supervisor-config-deploy"
    - "service-omni-supervisor-permset-assign"
    - "service-omni-supervisor-surface-deploy"
    - "service-omni-supervisor-users-create"
    - "service-omni-work-skill-routing-configure"
  accessCheck:
    - type: license
      value: ServiceCloud
  cliTools:
    - tool: ["jq"]
      semver: ">=1.6"
    - tool: ["python3"]
      semver: ">=3.8"
    - tool: ["sf"]
      semver: ">=2.139.6"

service-omni-channel-setup-coordinate

Align an org toward a working Omni-Channel setup: detect what already exists and create or deploy only the missing pieces, up to a routed environment with agents, queues, presence statuses, and permissions. Full create-and-bind routing (queue + `QueueRoutingConfig` + outbound routing flow) is provided for `Case` and `VoiceCall`; `Incident` and `MessagingSession` are **verified/adopted only** by this coordinator — it reports their state and reuses existing config but does not create a missing queue/QRC/flow for them (use `service-agentforce-human-escalation-configure` for a created-and-bound `MessagingSession` handoff). This is a coordinator — it sequences the child leaf skills against a canonical set of steps and performs no writes of its own. Each leaf owns one primitive; the coordinator resolves per-org IDs, passes them between leaves, and enforces a shared reuse-vs-create and safety contract. It blocks with a click-path only for prerequisites an operator must action (a missing feature license, or a target sObject that is not enabled).

`python3` is listed only because the bundled contract tests (`scripts/tests/test_omni_contracts.py`) use it; running the coordinator itself needs only `jq` and `sf`.

Inputs

Confirm these once, up front, before any write:

• Agent count (default `3`, range `1..10`) and supervisor count (default `1`, range `1..5`).
• Real login email (used for password-reset flows).
• `routing_targets` (default `["Case"]`) — any subset of `Case | Incident | MessagingSession | VoiceCall`. Only `Case` and `VoiceCall` get full create-queue + QRC + routing-flow; `Incident` and `MessagingSession` are verified/adopted (report-only).
• Service-channel strategy — reuse standard (`Cases`, `sfdc_livemessage`, default) or create a custom channel.
• Agent/supervisor profile — the driver provisions users on the `Service Cloud User` profile by default (Omni needs a Service Cloud license). Some orgs ship that license under a differently named profile (e.g. `Service Cloud`); override via `OMNI_AGENT_PROFILE` / `OMNI_SUPERVISOR_PROFILE` without editing the script. The user-create leaves block if the named profile is absent.
• Runtime proof (optional) — `OMNI_RUNTIME_PROOF=1` makes the routing-flow leaf fire the trigger (fail-soft); `OMNI_RUNTIME_PROOF_REQUIRED=1` makes proof blocking. QueueBased proof requires `PendingServiceRouting` or `AgentWork`. SkillsBased proof requires a `PendingServiceRouting` with at least one `SkillRequirement`, which is the acceptance signal that `WorkSkillRouting` actually ran. The throwaway record is always cleaned up.
• Queue selection (optional) — set `OMNI_CASE_QUEUE_DEVELOPER_NAME`, `OMNI_VOICE_QUEUE_DEVELOPER_NAME`, `OMNI_INCIDENT_QUEUE_DEVELOPER_NAME`, or `OMNI_MESSAGING_QUEUE_DEVELOPER_NAME` when the target must use a specific existing or canonical queue. Without an override, each leaf uses its target-derived default.
• Routing-config selection (optional) — set `OMNI_CASE_ROUTING_CONFIG_DEVELOPER_NAME` or `OMNI_VOICE_ROUTING_CONFIG_DEVELOPER_NAME` to select an existing QRC explicitly. When only a queue override is supplied, the coordinator first adopts that queue's linked `QueueRoutingConfig.DeveloperName`; it creates the canonical QRC only when the queue has no linked config.
• Queue routing controls (optional) — `OMNI_QRC_PUSH_TIMEOUT` sets the agent acceptance timeout and `OMNI_QRC_CAPACITY_PERCENTAGE` selects percentage capacity (for example, `100` for a VoiceCall that consumes the agent's full capacity). The coordinator passes both values to every QRC target.
• Routing mode — `OMNI_ROUTING_TYPE=QueueBased|SkillsB