forcedotcom/sf-skills / plugins/builder/service-omni/skills/service-omni-sidebar-configure
service-omni-sidebar-configure
VerifiedUse to enable or verify the Omni-Channel sidebar on a Lightning console app. Triggers: enable the Omni sidebar, pin Omni-Channel in a console app, configure the Omni sidebar, turn on the Omni-Channel utility region, verify the pinned Omni widget. Do not use for Aura apps, standard apps, utility-bar-only Omni widgets, or to create a console app.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.1 KB |
| references/api-notes.md | markdown | 2.6 KB |
| scripts/enable-and-report.shexecutable | script | 13.5 KB |
| scripts/tests/_bootstrap.py | script | 6.1 KB |
| scripts/tests/test_sidebar_contracts.pyexecutable | script | 5.4 KB |
references/api-notes.md
View on GitHub# API notes — service-omni-sidebar-configure
## The setting
The Omni-Channel **sidebar** (the pinned Omni utility region docked to the side of a console
workspace) is controlled by a single boolean on the `CustomApplication` metadata:
```xml
<isOmniPinnedViewEnabled>true</isOmniPinnedViewEnabled>
```
- It is a **per-app** setting on a Lightning **console** app — not an org-level `OmniChannelSettings`
flag. Enabling Omni-Channel org-wide (`service-omni-base-settings-configure`) is a prerequisite,
but does not pin the sidebar on any app.
- When absent, the platform treats it as `false`. This skill therefore inserts the element when it
is missing rather than assuming a default.
## XSD ordering
`CustomApplication` enforces element order. The `is*` booleans
(`isNavAutoTempTabsDisabled`, `isNavPersonalizationDisabled`, `isNavTabPersistenceDisabled`,
`isOmniPinnedViewEnabled`) precede `<label>`. The skill inserts `<isOmniPinnedViewEnabled>`
immediately before the first top-level `<label>`, which keeps the payload schema-valid whether or
not the other booleans are present. If a future release reorders the schema and the deploy fails
with an XSD-order error, adjust the insertion anchor here.
## Detecting console apps (auto-detect path)
When no app name is supplied, candidates come from the Tooling API:
```sql
SELECT DeveloperName, Label FROM AppDefinition WHERE UiType='Lightning' AND NavType='Console'
```
`AppDefinition.DeveloperName` matches the `CustomApplication` DeveloperName used for retrieve/deploy
for custom apps. The skill adopts a target automatically **only** when exactly one row is returned;
zero or many → `blocked` so it can never pin the wrong app. Standard apps surfaced by this query are
generally not deployable as `CustomApplication`; if one is named explicitly the retrieve returns no
`.app-meta.xml` and the skill blocks with a clear message.
## Retrieve / deploy
- Retrieve and deploy use explicit `--metadata "CustomApplication:<name>"` (never `--source-dir`) so
no sibling metadata can piggyback.
- The deploy runs `--async` and polls `sf project deploy report` to a terminal state — a synchronous
watched deploy can raise `ClientTimeoutError` under org load even when the server-side deploy
succeeds (same false-red class handled by the other Omni leaves).
- Metadata deploys are atomic, so a failed deploy leaves the app unchanged; the skill then reports
`blocked` and never claims partial success.
- Success is confirmed by a **re-retrieve** that reads `isOmniPinnedViewEnabled` back as `true`; a
green deploy that does not round-trip the flag is reported `blocked`, not `enabled`.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |