Service Omni Channel Setup Coordinate

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 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 (silent, mandatory, before any 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. 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-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).