service-omni-base-settings-configure

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

service-omni-base-settings-configure

Enable the five

OmniChannelSettings

booleans (

enableOmniChannel

enableOmniAutoLoginPrompt

enableOmniSecondaryRoutingPriority

enableOmniSkillsRouting

enableOmniStatusCapModel

) via a single Metadata API deploy. Nothing downstream — queues, presence statuses, routing flows — works without

enableOmniChannel=true

, so this must be the first write in an Omni setup sequence. The skill probes first and deploys only when a toggle is false or missing.

通过一次Metadata API部署启用五项

OmniChannelSettings

布尔值（

enableOmniChannel

、

enableOmniAutoLoginPrompt

、

enableOmniSecondaryRoutingPriority

、

enableOmniSkillsRouting

、

enableOmniStatusCapModel

）。如果

enableOmniChannel=true

未启用，所有下游组件——队列、在线状态、路由流——都无法正常工作，因此这必须是Omni设置流程中的首个写入操作。该工具会先探测状态，仅在开关为false或缺失时才进行部署。

Inputs

bash

bash scripts/configure-and-report.sh run  <org-alias>   # detect; deploy if needed; re-verify
bash scripts/configure-and-report.sh plan <org-alias>   # read-only: detect only, never deploys

org-alias

is the only input. All five toggles are always set to

true

— the skill takes no per-toggle overrides; a caller who wants a subset should use

platform-metadata-deploy

with their own

OmniChannel.settings-meta.xml

bash

bash scripts/configure-and-report.sh run  <org-alias>   # detect; deploy if needed; re-verify
bash scripts/configure-and-report.sh plan <org-alias>   # read-only: detect only, never deploys

org-alias

是唯一的输入参数。所有五项开关始终设置为

true

——该工具不支持单独覆盖单个开关；如果需要仅启用部分开关，调用者应使用

platform-metadata-deploy

并自行提供

OmniChannel.settings-meta.xml

文件。

Preconditions and safety

Target org authenticated via
```
sf
```
CLI (My Domain URL, not
```
.lightning.force.com
```
), Service Cloud license present,
```
sf
```
CLI ≥ 2.139.6.
Production guardrail: the writer 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. This permits CDOs (
```
IsSandbox=false
```
with a non-null
```
TrialExpirationDate
```
); do not weaken it to a bare
```
IsSandbox
```
check.

目标组织已通过
```
sf
```
CLI完成身份验证（使用My Domain URL，而非
```
.lightning.force.com
```
），具备Service Cloud许可证，且
```
sf
```
CLI版本≥2.139.6。
生产环境防护： 脚本会计算
```
safe_to_write
```
的值，当组织为沙盒（
```
IsSandbox
```
为true）、试用版到期日期不为空（
```
TrialExpirationDate != null
```
），或组织类型属于{Developer Edition, Base Edition}时，该值为true；若值为false，则会阻止写入且无法覆盖。此规则允许CDO（
```
IsSandbox=false
```
但试用版到期日期非空）；请勿将其简化为仅检查
```
IsSandbox
```
的判断逻辑。

Run

configure-and-report.sh

is the canonical entry point:

run — probe; if all five are already enabled, emit
```
reused
```
(no deploy); otherwise run the
```
safe_to_write
```
guard, deploy the explicit
```
assets/force-app/main/default/settings/OmniChannel.settings-meta.xml
```
source file with all five
```
true
```
(a
```
SucceededPartial
```
is treated as failure), re-probe, and emit
```
configured
```
iff all five are now true, else
```
blocked
```
. The explicit source path bypasses source-tracking no-op decisions when the org value has drifted.
plan — probe only; emit
```
reused
```
if all enabled, else
```
action_needed
```
. Never deploys.

The probe retrieves

Settings:OmniChannel

and takes 1–2 minutes (Metadata retrieve is slow); this is expected. The deploy runs from

assets/

(a valid DX project) and names the settings file with

--source-dir

; its template is never mutated at runtime, so the skill stays reproducible and does not report "No local changes to deploy" solely because local source tracking is clean.

configure-and-report.sh

是标准入口点：

run — 探测状态；如果五项开关均已启用，则输出
```
reused
```
（不执行部署）；否则执行
```
safe_to_write
```
防护检查，部署
```
assets/force-app/main/default/settings/OmniChannel.settings-meta.xml
```
源文件（所有开关均设为
```
true
```
，若部署结果为
```
SucceededPartial
```
则视为失败），重新探测状态，只有当所有五项开关均为true时才输出
```
configured
```
，否则输出
```
blocked
```
。明确指定源路径可避免因组织值偏离导致的源跟踪无操作决策。
plan — 仅探测状态；如果所有开关均已启用则输出
```
reused
```
，否则输出
```
action_needed
```
。绝不会执行部署操作。

探测操作会获取

Settings:OmniChannel

，耗时1-2分钟（Metadata检索速度较慢），这属于正常情况。部署操作从

assets/

（一个有效的DX项目）执行，并通过

--source-dir

指定设置文件；其模板在运行时不会被修改，因此该工具的执行结果可重现，且不会仅因本地源跟踪状态干净而报告“无本地更改可部署”。

Behavior

Whole-document writes.

Settings

is a whole-document metadata type — the Metadata API does not accept partial updates, so the skill always deploys the full file rather than PATCHing individual toggles.

Login-behavior gap. The Omni login-behavior radio (Setup → Omni-Channel Settings → "Define login behavior when an agent opens a new window/tab") has no public API on v66. The report always surfaces its click-path — even on a no-op

reused

run — so a "nothing to do" result never hides the one manual action.

enableOmniAutoLoginPrompt

still deploys cleanly (other Omni features may depend on it internally) but does not drive that radio.

Fail-closed verify. After a deploy the skill re-probes and requires all five toggles true; a deploy that reports success but does not stick (an uncommon org-level restriction) blocks rather than reporting success.

全文档写入：

Settings

是一种全文档元数据类型——Metadata API不接受部分更新，因此该工具始终部署完整文件，而非对单个开关进行PATCH操作。

登录行为差异：在v66版本中，Omni登录行为单选按钮（设置→Omni-Channel设置→“定义代理打开新窗口/标签页时的登录行为”）没有公开API。报告总会显示其操作路径——即使在无操作的

reused

运行中也是如此，因此“无需操作”的结果绝不会隐藏这一唯一的手动操作。

enableOmniAutoLoginPrompt

仍可正常部署（其他Omni功能可能在内部依赖它），但无法控制该单选按钮。

失败闭合验证：部署完成后，工具会重新探测状态，要求所有五项开关均为true；如果部署报告成功但设置未生效（罕见的组织级限制），则会阻止后续操作而非报告成功。

Output contract

configure-and-report.sh

emits a single JSON object with

status

∈

configured

reused

action_needed

blocked

, a top-level

all_enabled

boolean the coordinator reads to gate downstream skills, full

before

after

toggle objects,

deploy_id

safe_to_write

manual_actions

, and

blocking_issue

```
configured
```
— a toggle was false, the deploy ran, and the re-probe shows all true (run mode).
```
reused
```
— all five were already true; no deploy.
```
action_needed
```
— plan mode saw a disabled toggle; nothing deployed.
```
blocked
```
—
```
safe_to_write=false
```
, the deploy failed or was
```
SucceededPartial
```
, or the re-probe still shows a false toggle.

manual_actions

always includes the login-behavior gap entry on non-blocked reports;

deploy_id

null

for

reused

action_needed

;

blocking_issue

names the failure only when

status: blocked

configure-and-report.sh

会输出一个JSON对象，其中

status

的取值为

configured

reused

action_needed

blocked

，顶层

all_enabled

布尔值供协调器用于控制下游工具的执行，还包含完整的

before

after

开关对象、

deploy_id

、

safe_to_write

、

manual_actions

和

blocking_issue

。

```
configured
```
— 存在开关为false的情况，已执行部署，且重新探测显示所有开关均为true（运行模式）。
```
reused
```
— 所有五项开关已启用；未执行部署。
```
action_needed
```
— 计划模式下检测到禁用的开关；未执行部署。
```
blocked
```
—
```
safe_to_write=false
```
、部署失败或结果为
```
SucceededPartial
```
，或重新探测仍显示存在开关为false。

在非阻塞报告中，

manual_actions

始终包含登录行为差异的操作项；

deploy_id

在

reused

action_needed

状态下为

null

；仅当

status: blocked

时，

blocking_issue

才会指明失败原因。

Limitations

Configures only
```
OmniChannelSettings
```
, always with all five toggles true — other
```
Settings
```
types belong to
```
platform-metadata-deploy
```
.
Cannot turn the login-behavior radio (no public API on v66) — it only surfaces the click-path.

仅配置
```
OmniChannelSettings
```
，且始终将所有五项开关设为true——其他类型的
```
Settings
```
需使用
```
platform-metadata-deploy
```
。
无法控制登录行为单选按钮（v66版本无公开API）——仅能显示其操作路径。

References

File	When to read
`references/api-notes.md`	Before a deploy — the five toggles' semantics, dependencies, and the login-behavior caveat

文件	阅读时机
`references/api-notes.md`	部署前——了解五项开关的语义、依赖关系以及登录行为的注意事项