---
name: service-omni-channel-setup-coordinate
description: "Use to stand up Omni-Channel headlessly: base settings, users, service channels, routing configs, queues and members, presence statuses, permissions, supervisor configuration, and Case or VoiceCall routing flows. Reuses existing records and creates missing ones. Optional stages cover Command Center V2 on supported releases, agent experience, and skills-based routing. TRIGGER when: set up Omni-Channel, configure Omni routing, provision Omni agents, provision Omni supervisors, or configure Case, Incident, MessagingSession, or VoiceCall routing. Do not use for Agentforce bots, one existing field change, or bare metadata deployment."
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-channel-inventory-analyze"
    - "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|SkillsBased` is optional. When all four `OMNI_WSR_ENTITY` / `OMNI_WSR_FIELD` / `OMNI_WSR_SKILL` / `OMNI_WSR_VALUE` inputs are supplied, the coordinator infers `SkillsBased`; otherwise it defaults to `QueueBased`. SkillsBased uses `OMNI_SKILL_OPTION=RunSBRRules` (the default), binds the provisioned agents to `OMNI_SBR_SKILL` (defaults to `OMNI_WSR_SKILL`), authors the WorkSkillRouting rule, and only then activates the flow. An incomplete mapping or mismatched SBR/WSR skill is rejected before any write. `OMNI_WSR_LABEL` optionally names the rule.
- Rep-experience stages (optional, default off) — `OMNI_REP_EXPERIENCE=1` adds presence user config (decline + decline reason + ACW) and the Omni sidebar. `OMNI_CONSOLE_APP=<app DeveloperName>` targets a specific console app; empty auto-detects one.
- Supervisor surface (always, after the config) — once `OmniSupervisorConfig` exists, the coordinator populates its standard action + tab surface (`OmniSupervisorConfigAction` / `OmniSupervisorConfigTab`) via the Data API. Just before the classic config deploy it also runs a read-only Command Center analysis that reports whether the org is on the classic surface or Command Center V2.
- Supervisor-config selection (optional) — set `OMNI_SUPERVISOR_CONFIG_DEVELOPER_NAME` to the exact classic `OmniSupervisorConfig.DeveloperName` that both the config and surface stages must reconcile. It defaults to `Omni_Supervisor`; use the override whenever the org has multiple configs so the coordinator never guesses. `OMNI_SUPERVISOR_CONFIG_MASTER_LABEL` optionally supplies the label when creating a new selected config.

Run it in plan or run mode:

```bash
bash scripts/integration-driver.sh --plan <org-alias> [agent_count] [routing_targets_csv] [supervisor_count]
bash scripts/integration-driver.sh --run  <org-alias> [agent_count] [routing_targets_csv] [supervisor_count]
```

`--plan` is a full read-only preview: each leaf runs its own detector and reports `reused`, `action_needed`, or `blocked`; a leaf whose prerequisite is not yet in place is reported as pending work rather than probed, so a plan never shows a misleading red for a step that is simply earlier in the sequence. A clean plan (all `reused`, exit 0) means the org is already configured; any yellow (exit 2) means work remains.

## Preconditions and safety

- Authenticated org via `sf` CLI using the My Domain URL (not `.lightning.force.com`).
- Service Cloud license with headroom for the agent count.
- `Incident` targets require the Incident Management feature enabled; `MessagingSession` requires Enhanced Messaging; `VoiceCall` requires Service Cloud Voice. The readiness check hard-fails with a click-path when a requested target sObject is absent.
- **Production guardrail:** `safe_to_write` is `true` iff any of `IsSandbox = true`, `TrialExpirationDate != null`, or `OrganizationType IN ('Developer Edition', 'Base Edition')`. The run hard-refuses when it is false. CDOs return `IsSandbox=false` with a non-null `TrialExpirationDate` and must be permitted, so `IsSandbox` alone is never the guard.

Readiness check (mandatory, before any write leaf runs):

1. `sf org display` → confirm the org alias is authenticated; refuse (exit 1) if not.
2. `Organization` (`IsSandbox`, `TrialExpirationDate`, `OrganizationType`) → compute `safe_to_write`; refuse (exit 1) if false.
3. `service-omni-channel-inventory-analyze` → capture the complete channel/routing baseline through the approved read-only aggregate operation; a blocked inventory prevents writes because the coordinator cannot safely establish the starting state.
4. Preflight entity availability → for each **non-`Case`** routing target, confirm the sObject exists via `EntityDefinition`; a missing target hard-fails with a feature-enablement click-path (exit 2). `Case` is assumed present and skipped.

Omni-Channel base-settings enablement is not a separate upfront probe — it is detected by the base-settings leaf (step 1), and downstream Omni-dependent leaves are deferred as pending in `--plan` until it is on. The driver does not pre-check `UserLicense` headroom or `ServicePresenceStatus`/`QueueRoutingConfig` availability in this readiness pass.

## Skills this coordinates

The coordinator delegates every write to a leaf skill. sObject-specific leaves (3, 5, 6, 6c, 7) loop once per routing target; the rest run once. For SkillsBased routing, steps 6a and 6b complete before any trigger flow is activated. Step 10a (`command-center-configure`) is opt-in through `OMNI_COMMAND_CENTER_V2=1`; step 10b (`command-center-analyze`) is a read-only advisory and always runs. Step 11a (`supervisor-surface-deploy`) always runs after the supervisor config succeeds. Leaves 12–13 are the opt-in rep-experience stages (`OMNI_REP_EXPERIENCE=1`).

| # | Child skill | Role |
|---|---|---|
| 0 | `service-omni-channel-inventory-analyze` | Capture the read-only cross-channel and routing baseline before any writes |
| 1 | `service-omni-base-settings-configure` | Deploy `Settings:OmniChannel` (5 toggles) |
| 2 | `service-omni-agent-users-create` | Provision the requested agent users |
| 3 | `service-omni-service-channel-configure` | Reuse the standard `ServiceChannel` for the target sObject, or deploy the canonical XML |
| 4 | `service-omni-queue-routing-config-deploy` | Upsert the target's `QueueRoutingConfig` (e.g. `Case_Routing_Config`, `Voice_Routing_Config`) |
| 5 | `service-omni-queue-deploy` | Discover or create (`--create-if-missing`) a `Queue` bound to the target sObject; align it to the QRC |
| 6 | `service-omni-queue-members-assign` | Assign users to the discovered queue |
| 6a | `service-omni-skills-based-routing-configure` | *(SkillsBased only)* Ensure the `Skill` and active agents' `SkillUser` bindings exist |
| 6b | `service-omni-work-skill-routing-configure` | *(SkillsBased only)* Author the required field-value → Skill rule before flow activation |
| 6c | `service-omni-routing-flow-deploy` | Deploy the record-triggered QueueBased or SkillsBased `Flow` for `Case`/`VoiceCall`; SkillsBased passes `skillOption=RunSBRRules` |
| 7 | `service-omni-presence-status-deploy` | Deploy `Available_<sObject>` bound to the matching channel and ensure a universal `Busy` status |
| 8 | `service-omni-permission-set-assign` | Assign the `Omni_Agent` PermissionSet to agent users; self-heals the bundled metadata when absent (run mode only) |
| 9 | `service-omni-supervisor-users-create` | Provision supervisor users |
| 10 | `service-omni-supervisor-permset-assign` | Assign the standard `ContactCenterSupervisor` PermissionSet to supervisor users |
| 10a | `service-omni-command-center-configure` | *(opt-in)* Enable Command Center V2 through preserved `OmniChannel.settings` and verify its seeded page and tab |
| 10b | `service-omni-command-center-analyze` | **Read-only advisory** — report whether the org is on the classic supervisor surface or Command Center V2; never writes, never hard-blocks |
| 11 | `service-omni-supervisor-config-deploy` | Deploy `OmniSupervisorConfig` binding supervisor users to the queues discovered in step 5 |
| 11a | `service-omni-supervisor-surface-deploy` | Populate the supervisor **action + tab surface** (`OmniSupervisorConfigAction` / `OmniSupervisorConfigTab`) on the config from step 11 |
| 12 | `service-omni-presence-user-config-deploy` | *(opt-in)* Deploy `PresenceUserConfig` + `PresenceDeclineReason` (decline + ACW) and assign the provisioned agents |
| 13 | `service-omni-sidebar-configure` | *(opt-in)* Set `CustomApplication.isOmniPinnedViewEnabled=true` to pin the Omni utility region on a console app |
| — | `platform-metadata-deploy` | Underlying Metadata API deploys used by the deploy leaves |

## Behavior

**Reuse-vs-create contract (enforced for every entity).** Query by `DeveloperName` (or the natural key); reuse a standard record when present (`Cases`, `sfdc_livemessage`); create from the leaf's bundled definition when nothing exists; reconcile idempotently when a same-named custom record exists — never duplicate, rename, or mutate the identity of a standard or managed record.

**Ordering and gating.** Leaves run in dependency order. Base settings are a hard prerequisite for every write below. For SkillsBased routing, agent `SkillUser` bindings (6a) and the `WorkSkillRouting` rule (6b) must succeed before the routing-flow leaf (6c) can activate the trigger. The flow also requires the queue (5) and its members (6), and it round-trips `FlowDefinitionView.ActiveVersionId` to prove the flow is Active. A required runtime proof does not pass merely because a PSR exists: SkillsBased requires at least one `SkillRequirement` on that PSR.

**Supervisor path.** Supervisor users (9) use the same Anonymous Apex `System.setPassword` model as agent users. Because a password literal can be captured in an `ApexLog` when a debug TraceFlag is active, both user-create leaves fail closed *before* the first `System.setPassword`: they prove via a SOQL-filtered Tooling API query (`ExpirationDate > now`) that no active TraceFlag exists for the running user, and if that cannot be positively proven they set no password at all (users left ACTIVE and `reset_required`, with a `security_warning`). They never delete logs, so unrelated audit logs are untouched. The supervisor permset leaf (10) assigns the standard `ContactCenterSupervisor` — never the custom `Omni_Supervisor`, whose license-gated permissions fail assignment — and a contract test asserts this wiring. With `OMNI_COMMAND_CENTER_V2=1`, the coordinator enables and verifies the V2 org preference through `service-omni-command-center-configure`; optional `OMNI_COMMAND_CENTER_*` booleans select its subordinate controls. A read-only Command Center analysis then reports the resulting supervisor surface and never hard-blocks (ambiguous detection is yellow, a clean read green). Once the classic config lands (11), the surface leaf (11a) inserts the standard action + tab companions (`OmniSupervisorConfigAction` / `OmniSupervisorConfigTab`) against the config's Id — plain Data API rows, so no metadata-file redeploy — and is idempotent (only missing types are inserted). It runs only after the config succeeds; a skipped or failed config skips the surface with a dependency note.

**Optional rep-experience stages.** With `OMNI_REP_EXPERIENCE=1`, presence user config (12) deploys a validator-safe `PresenceUserConfig` with its decline reason and assigns every resolved agent username, including reused users. Sidebar (13) pins the Omni utility region on `OMNI_CONSOLE_APP`, or auto-detects a single console app. SkillsBased routing is not a cosmetic rep-experience stage: when requested, its SkillUser and WorkSkillRouting prerequisites run before flow activation.

**Login-behavior gap.** The login-behavior radio (Setup → Omni-Channel Settings → "Define login behavior when an agent opens a new window/tab") has no public API on v66. After base settings deploy, the coordinator surfaces the exact click-path; it does not attempt to flip it via `enableOmniAutoLoginPrompt`, which deploys but does not drive the radio. See `references/gap-catalog.md`.

**Credentials.** Generated passwords are moved into a single restricted `CREDENTIALS.json` (mode 0600) and redacted from every other artifact. The write is atomic and fail-closed: on any redaction or verification failure the plaintext artifact is removed and the run aborts, so no plaintext password is left in the artifacts directory. The operator reads `CREDENTIALS.json` once, distributes securely, then deletes it.

## Output contract

The one deliverable is a single report file. As the final action you MUST use the `Write` tool to save the complete report to `omni-coordinate-report.md` in the current working directory — never deliver it only in chat. In `--run` mode it states what *is* (created resource, reused standard record, resolved decision) — no hedging. In `--plan` mode it states each leaf's honest disposition (`reused` / `action_needed` / pending) plus the coordinator's plan JSON (`dry_run: true`). Each leaf also writes its full JSON outcome (including every created record Id and deploy Id) to a per-skill artifact under the run's artifacts directory — that is the audit trail; user-facing output uses human-readable names, not record Ids. See `examples/output-templates.md` for the report shape.

**Run artifacts (run mode).** Alongside the per-skill artifacts, a `--run` writes three files into the run's artifacts directory (paths echoed in the report JSON as `run_log`, `deploy_ids_file`, `teardown_script`): `run.log` (sanitized, human-readable step sequence and result), `deploy_ids.json` (a provenance manifest — each entry's `provenance` is `created` / `updated` / `reused`, with resource ids, a `before` snapshot, and a pointer to the authoritative per-skill artifact), and `teardown.sh` (an auto-generated, **dry-run** reverse-dependency-order plan). The teardown script prints what a teardown would `REMOVE` (run-created), `RESTORE` (updated, with prior values), or `KEEP` (adopted/reused — never deleted) and makes no changes; destructive execution stays manual by design (see Limitations).

Report content rules:

- Report concrete outcomes, never intentions.
- Surface the login-behavior click-path whenever setup ran, even if the operator declined to turn the radio.
- Surface any hard fail from step 5 (no queue bound) as a manual action with a click-path.

## Limitations

- Routing-flow deploy covers `Case` and `VoiceCall` only.
- Classic `OmniSupervisorConfig`, including its standard action and tab surface, is supported. Command Center V2 is an explicit opt-in (`OMNI_COMMAND_CENTER_V2=1`) and runs only when the org's Metadata API exposes the V2 settings; otherwise the configure leaf fails closed. Custom actions, FlexiPages, AWS dashboards, and AI-agent surfaces still need external references and separate setup.
- The rep-experience stages (presence user config, decline reasons, sidebar) run only with `OMNI_REP_EXPERIENCE=1`. SkillsBased routing is selected explicitly or inferred from a complete `OMNI_WSR_*` mapping and runs independently of that flag.
- Teardown is **plan-only**: `--run` emits `deploy_ids.json` (a provenance manifest) and a dry-run `teardown.sh` that prints the reverse-order removal/restore plan, but does not execute dest