service-omni-supervisor-config-deploy

Deploy the classic Omni-Channel Supervisor Configuration (

OmniSupervisorConfig

) to a Salesforce org in a single Metadata API deploy.

OmniSupervisorConfig

is a full Metadata API type whose XSD embeds every companion as a repeatable child element, so the whole configuration — parent plus companions — lands atomically from one

.omniSupervisorConfig-meta.xml

file, and Salesforce rolls the companions back together on a partial failure. By default the deploy binds supervisors explicitly by user and lists the queues they monitor; profile scope is optional (see Behavior).

Inputs

bash scripts/deploy-and-report.sh <org-alias> [supervisor_count] [additional_queues_csv] [profiles_csv] [skill_visibility] [config_developer_name]

org-alias

(required) — must resolve via

sf org display --target-org <alias>

```
supervisor_count
```
(optional, default
```
1
```
, range
```
1..5
```
) — how many active
```
supervisor{N}.<suffix>@example.com
```
users to detect and bind.
```
additional_queues_csv
```
(optional) — queue DeveloperNames to bind. When the coordinator supplies this list it is authoritative; when omitted, the canonical
```
CaseQueue
```
,
```
messagingqueue
```
defaults are used. Every requested queue must already exist on the org.
```
profiles_csv
```
(optional) — opt into profile-based fallback scope; supply metadata profile fullNames (e.g.
```
Standard,ServiceCloud
```
). Omit it to bind supervisors by user only.
```
skill_visibility
```
(optional, or
```
OMNI_SUPERVISOR_SKILL_VISIBILITY
```
) —
```
AllSkills
```
or
```
AnySkill
```
. Omitted values preserve an existing config's selection; a new config defaults to
```
AllSkills
```
.
```
config_developer_name
```
(optional, or
```
OMNI_SUPERVISOR_CONFIG_DEVELOPER_NAME
```
; default
```
Omni_Supervisor
```
) — the exact classic
```
OmniSupervisorConfig.DeveloperName
```
to create or reconcile. Supply it when an org has multiple supervisor configurations; the skill never guesses between candidates.
```
OMNI_SUPERVISOR_CONFIG_MASTER_LABEL
```
optionally sets the label for a new config. Existing labels are preserved by default.

Preconditions and safety

Target org authenticated via
```
sf
```
CLI, Service Cloud license present,
```
sf
```
CLI ≥ 2.139.6.
Active supervisor users exist; their supervisor access is granted separately by
```
service-omni-supervisor-permset-assign
```
.
Omni-Channel base settings are enabled (
```
service-omni-base-settings-configure
```
) and the monitored queues exist (
```
service-omni-queue-deploy
```
).
Production guardrail: the script 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. Any unmet precondition returns
```
status: blocked
```
with a
```
blocking_issue
```
and a click-path.

Run

One script does detect, deploy, and verify:

bash

bash scripts/deploy-and-report.sh <org-alias> [supervisor_count] [additional_queues_csv] [profiles_csv] [skill_visibility] [config_developer_name]

It resolves the deploy artifact's tokens from live org state (discovered supervisor users, verified queues, and — only when

profiles_csv

is given — validated profiles), materializes the selected DeveloperName into the metadata filename and package manifest, then re-queries that same selected config to confirm the parent and its companion rows persisted before emitting JSON to stdout. The coordinator (

service-omni-channel-setup-coordinate

) invokes it with the authoritative queue list and selected supervisor config; standalone runs use the canonical defaults.

Behavior

Companions. The deployed config always carries

omniSupervisorConfigUser

(one per supervisor) and

omniSupervisorConfigQueue

(one per monitored queue). It follows the same single-file Metadata deploy shape as

service-omni-service-channel-configure

and

service-omni-presence-status-deploy

Profile scope is a fallback, off by default. Core resolves a supervisor's configuration by

OmniSupervisorConfigUser

first, and only falls back to

OmniSupervisorConfigProfile

— matched against that supervisor's own profile — when the supervisor has no user row (

RealTimeQueueServiceImpl.getSupervisorConfigId

). Because this skill binds every supervisor by user, profile companions are unnecessary and are omitted unless you pass

profiles_csv

. When supplied, values must be metadata fullNames (the

<profile>

element resolves against the fullName —

Standard

ServiceCloud

Admin

— not the SOQL

User.Profile.Name

label); the skill validates each against

sf org list metadata -m Profile

and blocks on any the org does not expose.

Idempotency and surface preservation. Status follows the Metadata deploy component state:

Unchanged

→

reused

Changed

→

updated

Created

→

created

. Any other state is a hard failure rather than a silent

reused

. Before updating an existing parent, the skill snapshots its reference-free

OmniSupervisorConfigAction

and

OmniSupervisorConfigTab

rows, validates that each can be recreated safely, then restores and re-queries them after the deploy. A custom/reference-bearing surface blocks before deployment instead of risking silent loss. When reconciling an existing config or verifying preservation, invoke only this skill; do not invoke

service-omni-supervisor-surface-deploy

, because adding standard rows afterward could mask a preservation failure. The companion surface skill remains responsible only for a separate request to add new standard actions or tabs.

Fail-closed verification. The deploy

status

must be

Succeeded

(not

SucceededPartial

). After the parent config is queryable, the script re-queries the child

OmniSupervisorConfigUser

and

OmniSupervisorConfigQueue

rows and requires at least the intended counts — the parent existing does not prove the companions landed. Every read must return a parseable

.result.records

array; an inconclusive read never counts as zero. Requested queues are validated against

^[A-Za-z0-9_]{1,80}$

before use, and every requested queue must exist or the run blocks (dropping one silently would under-provision the config).

Output contract

A single JSON object to stdout.

status

is one of

created

updated

reused

, or

blocked

. The object also carries

config_developer_name

config_id

skill_visibility

surface_preservation

snapshot/restoration counts,

supervisor_users_bound

supervisor_users_count

queues_bound

queues_count

queue_source

(

caller_supplied

canonical_default

), the re-queried

verified_companion_user_count

verified_companion_queue_count

deploy_id

state

manual_actions

, and

blocking_issue

blocking_issue

null

unless

status: blocked

, in which case it names the missing prerequisite with a click-path in

manual_actions

. Re-running an unchanged config returns

reused

and performs no functional change.

Org-side spot-check:

sql

SELECT Id, DeveloperName, MasterLabel FROM OmniSupervisorConfig WHERE DeveloperName='<config_developer_name>'
SELECT COUNT(Id) FROM OmniSupervisorConfigUser  WHERE OmniSupervisorConfigId = :configId
SELECT COUNT(Id) FROM OmniSupervisorConfigQueue WHERE OmniSupervisorConfigId = :configId

Limitations

Populates user and queue companions (plus optional profile scope). Existing reference-free Action and Tab rows are preserved across an update; new standard rows are added separately by
```
service-omni-supervisor-surface-deploy
```
. Custom-action, FlexiPage, AWS-dashboard, and AI-agent rows require external references and therefore block an update rather than being reconstructed incompletely.
Binds supervisor users discovered by the
```
supervisor{N}.<suffix>@example.com
```
pattern; it does not create them.
Does not change AgentWork sharing because that org-wide access control is separate from
```
OmniSupervisorConfig
```
. Use
```
service-omni-agent-work-sharing-configure
```
for supported metadata detection and the explicitly confirmed
```
Private
```
to
```
Read
```
operation.
Does not activate the Command Center V2 runtime (a separate settings flip).

References

File When to read

File	When to read
`references/api-notes.md`	On a deploy failure — field-by-field `OmniSupervisorConfig` schema and companion sObject semantics
`assets/force-app/main/default/omniSupervisorConfigs/Omni_Supervisor.omniSupervisorConfig-meta.xml`	The token-templated deploy artifact ( `__MASTER_LABEL__` , `__SUPERVISOR_USERS_XML__` , `__PROFILE_SCOPE_XML__` , `__QUEUE_LIST_XML__` , `__SKILL_VISIBILITY__` ); it is materialized under the selected DeveloperName at runtime
`assets/package.xml` , `assets/sfdx-project.json`	Manifest and project scaffold materialized into the temp deploy dir

references/api-notes.md

On a deploy failure — field-by-field

OmniSupervisorConfig

schema and companion sObject semantics

assets/force-app/main/default/omniSupervisorConfigs/Omni_Supervisor.omniSupervisorConfig-meta.xml

The token-templated deploy artifact (

__MASTER_LABEL__

__SUPERVISOR_USERS_XML__

__PROFILE_SCOPE_XML__

__QUEUE_LIST_XML__

__SKILL_VISIBILITY__

); it is materialized under the selected DeveloperName at runtime

assets/package.xml

assets/sfdx-project.json

Manifest and project scaffold materialized into the temp deploy dir

service-omni-supervisor-config-deploy

NPX Install

Tags

SKILL.md Content

service-omni-supervisor-config-deploy

Inputs

Preconditions and safety

Run

Behavior

Output contract

Limitations

References