service-omni-sidebar-configure

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

service-omni-sidebar-configure

Enable the Omni-Channel sidebar — the pinned Omni utility region that docks to the side of a Lightning console app — by setting

isOmniPinnedViewEnabled=true

on that app's

CustomApplication

metadata and confirming the flag round-trips. This is the recommended Omni surface for console/demo orgs: reps see incoming work, presence, and the work list docked beside the record, rather than only in the collapsible utility bar. It runs once per console app and is invoked by

service-omni-channel-setup-coordinate

as the final rep-experience step.

通过在Lightning控制台应用的

CustomApplication

元数据中设置

isOmniPinnedViewEnabled=true

并确认该标记的往返生效，即可启用Omni-Channel侧边栏——固定在Lightning控制台应用侧边的Omni实用程序区域。这是控制台/演示组织推荐的Omni界面：客服代表可以在记录旁看到待处理工作、在线状态和工作列表，而不仅仅是在可折叠的实用程序栏中查看。该操作针对每个控制台应用运行一次，并由

service-omni-channel-setup-coordinate

作为客服体验设置的最后一步调用。

Inputs

输入参数

bash

bash scripts/enable-and-report.sh <org-alias> [app_developer_name]

```
org-alias
```
(required).
```
app_developer_name
```
(optional). The
```
CustomApplication
```
DeveloperName of the Lightning console app. When omitted, the skill queries
```
AppDefinition
```
for Lightning console apps: exactly one → adopt it; zero or many →
```
blocked
```
(name it explicitly).

bash

bash scripts/enable-and-report.sh <org-alias> [app_developer_name]

```
org-alias
```
（必填）。
```
app_developer_name
```
（可选）。Lightning控制台应用的
```
CustomApplication
```
开发者名称。若省略该参数，此技能会查询
```
AppDefinition
```
获取Lightning控制台应用：若恰好找到一个，则采用该应用；若找到零个或多个，则状态为
```
blocked
```
（需明确指定应用名称）。

Preconditions and safety

前置条件与安全要求

Target org authenticated via
```
sf
```
CLI, Service Cloud license,
```
sf
```
CLI ≥ 2.139.6.
Omni-Channel base settings enabled (
```
service-omni-base-settings-configure
```
).
The target must be a Lightning console app that is deployable as
```
CustomApplication
```
metadata. Standard apps and Aura apps are out of scope.
The three-way
```
safe_to_write
```
production guard applies.

目标组织已通过
```
sf
```
CLI完成身份验证，拥有Service Cloud许可证，且
```
sf
```
CLI版本≥2.139.6。
已启用Omni-Channel基础设置（
```
service-omni-base-settings-configure
```
）。
目标必须是可作为
```
CustomApplication
```
元数据部署的Lightning控制台应用。标准应用和Aura应用不在适用范围内。
需启用三方
```
safe_to_write
```
生产环境保护机制。

Run

运行方式

enable-and-report.sh

resolves the target app, retrieves its

CustomApplication

, and reads the current

isOmniPinnedViewEnabled

value:

already
```
true
```
→
```
reused
```
(no deploy).
```
false
```
or absent → sets it to
```
true
```
and deploys the single
```
CustomApplication
```
in one atomic Metadata API call, then re-retrieves to confirm the flag is
```
true
```
before reporting success.

The deploy uses explicit

--metadata "CustomApplication:<name>"

(never

--source-dir

) and is done on its own — Metadata deploys are atomic, so the app is left unchanged on any failure.

enable-and-report.sh

会解析目标应用，获取其

CustomApplication

元数据，并读取当前

isOmniPinnedViewEnabled

的值：

若值已为
```
true
```
→ 状态为
```
reused
```
（无需部署）。
若值为
```
false
```
或不存在 → 将其设置为
```
true
```
，并通过一次原子性Metadata API调用部署单个
```
CustomApplication
```
，然后重新获取元数据以确认该标记已变为
```
true
```
，之后才会报告操作成功。

部署时使用显式的

--metadata "CustomApplication:<name>"

参数（绝不使用

--source-dir

），且独立完成部署——Metadata部署是原子性的，因此任何失败都会使应用保持原有状态。

Behavior

行为特性

Idempotent + non-destructive. The skill only flips the single boolean; it never rewrites tabs, brand, or nav config. When the field is missing it is inserted in its XSD-ordered position (immediately before

<label>

); when present its value is replaced in place.

Auto-detect is conservative. It adopts an app automatically only when exactly one Lightning console app exists, so it can never silently pin the wrong app on an org with several.

幂等性 + 非破坏性：该技能仅修改单个布尔值；绝不会重写标签页、品牌或导航配置。若该字段缺失，会将其插入到XSD规定的位置（紧邻

<label>

之前）；若字段已存在，则直接替换其值。

自动检测机制保守：仅当恰好存在一个Lightning控制台应用时，才会自动采用该应用，因此绝不会在包含多个应用的组织中静默地错误固定应用。

Output contract

输出约定

A single JSON object:

status

∈

enabled

reused

blocked

app_developer_name

app_label

before

(bool),

after

(bool),

deploy_id

manual_actions

blocking_issue

```
enabled
```
— the flag was
```
false
```
/absent and is now verified
```
true
```
.
```
reused
```
— the flag was already
```
true
```
.
```
blocked
```
— no/many console apps found, retrieve/deploy failure, or the post-verify did not confirm
```
true
```
;
```
blocking_issue
```
explains and
```
manual_actions
```
names the fix or prerequisite skill.

返回单个JSON对象：

status

∈

enabled

reused

blocked

，包含

app_developer_name

、

app_label

、

before

（布尔值）、

after

（布尔值）、

deploy_id

、

manual_actions

、

blocking_issue

字段。

```
enabled
```
：该标记原本为
```
false
```
或不存在，现已验证为
```
true
```
。
```
reused
```
：该标记原本已为
```
true
```
。
```
blocked
```
：未找到控制台应用或找到多个应用、获取/部署失败，或验证后未确认标记为
```
true
```
；
```
blocking_issue
```
字段会说明问题原因，
```
manual_actions
```
字段会列出修复方法或所需的前置技能。

Limitations

限制说明

One app per invocation; run again for each console app that needs the sidebar.
Lightning console
```
CustomApplication
```
only — not Aura, not standard apps, not the utility-bar Omni widget.
Does not create or lay out the console app, its tabs, or the Omni utility item.

每次调用仅处理一个应用；每个需要启用侧边栏的控制台应用需单独运行一次。
仅适用于Lightning控制台
```
CustomApplication
```
——不适用于Aura应用、标准应用或仅含实用程序栏的Omni组件。
不会创建或布局控制台应用、其标签页或Omni实用程序项。

References

参考文档

File	When to read
`references/api-notes.md`	CustomApplication `isOmniPinnedViewEnabled` schema/order, AppDefinition detection query, and retrieve/deploy notes

文件	阅读场景
`references/api-notes.md`	CustomApplication `isOmniPinnedViewEnabled` 的架构/顺序、AppDefinition检测查询，以及获取/部署相关说明