Back to Details

service-omni-presence-user-config-deploy

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

service-omni-presence-user-config-deploy

service-omni-presence-user-config-deploy

Deploy an Omni PresenceUserConfig (the "presence configuration" that governs how work is offered to agents) together with the PresenceDeclineReason it references, in one atomic Metadata API package. The decline / auto-accept / decline-reason / ACW fields have cross-field validators — enabling Decline requires Auto-Accept off, Decline Reason requires Decline on, and the ACW timer must be paired with its max time — so they can only be set correctly as a single whole-record write, not field-by-field. This skill encodes that consistent record and assigns it to the given agents. It runs after 
service-omni-agent-users-create
/ 
service-omni-presence-status-deploy
and is invoked by 
service-omni-channel-setup-coordinate
as a rep-experience step.
以原子化Metadata API包的形式，部署Omni PresenceUserConfig（用于控制工作分配给座席方式的“在线状态配置”）及其引用的PresenceDeclineReason。拒绝/自动接受/拒绝原因/ACW字段存在跨字段验证规则——启用拒绝需关闭自动接受，启用拒绝原因需开启拒绝，且ACW计时器必须与其最大时长配对——因此这些字段只能通过单次整记录写入正确设置，无法逐字段设置。本技能封装了这套一致的配置记录，并将其分配给指定座席。它在
service-omni-agent-users-create
/ 
service-omni-presence-status-deploy
之后运行，作为客服体验步骤被
service-omni-channel-setup-coordinate
调用。

Inputs

Inputs

bash
bash scripts/deploy-and-report.sh <org-alias> [config_developer_name] [agent_usernames_csv]
  • org-alias
    (required).
  • config_developer_name
    (optional, default 
    Omni_Demo_Presence_Config
    ).
  • agent_usernames_csv
    (optional). Comma-separated Usernames (
    …@…
    ) and/or 15/18-char User Ids (
    005…
    ) to assign; Ids are resolved to usernames (metadata assigns by username). May also be set via 
    AGENT_USERNAMES_CSV
    . Empty → the config deploys with no user assignments.
Env overrides: 
DECLINE_REASON_LABEL
(default 
Training
), 
DECLINE_REASON_DEVELOPER_NAME
(default derived from the label), 
CAPACITY
(default 
5
, 1–100), 
ACW_SECONDS
(default 
60
, 10–3600), 
PRESENCE_STATUS_ON_DECLINE
(optional ServicePresenceStatus DeveloperName).
bash
bash scripts/deploy-and-report.sh <org-alias> [config_developer_name] [agent_usernames_csv]
  • org-alias
    （必填）。
  • config_developer_name
    （可选，默认值为
    Omni_Demo_Presence_Config
    ）。
  • agent_usernames_csv
    （可选）。以逗号分隔的用户名（
    …@…
    ）和/或15/18位用户ID（
    005…
    ），用于分配配置；ID会被解析为用户名（元数据通过用户名分配）。也可通过
    AGENT_USERNAMES_CSV
    环境变量设置。若留空，则部署的配置不包含用户分配。
环境变量覆盖：
DECLINE_REASON_LABEL
（默认值为
Training
）、
DECLINE_REASON_DEVELOPER_NAME
（默认值由标签派生）、
CAPACITY
（默认值为
5
，取值范围1–100）、
ACW_SECONDS
（默认值为
60
，取值范围10–3600）、
PRESENCE_STATUS_ON_DECLINE
（可选，ServicePresenceStatus的开发者名称）。

Preconditions and safety

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
    ).
  • Any 
    PRESENCE_STATUS_ON_DECLINE
    must already exist (
    service-omni-presence-status-deploy
    ).
  • 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
    ）。
  • 任何指定的
    PRESENCE_STATUS_ON_DECLINE
    必须已存在（
    service-omni-presence-status-deploy
    ）。
  • 启用了三重
    safe_to_write
    生产环境防护机制。

Run

Run

deploy-and-report.sh
materializes two components into a temp DX project and deploys them in one call:
  1. PresenceDeclineReason:<reason>
    — the decline reason (label only).
  2. PresenceUserConfig:<config>
    — capacity + label, 
    enableAutoAccept=false
    , 
    enableDecline=true
    , 
    enableDeclineReason=true
    , 
    declineReasons=<reason>
    , 
    hasAfterConvoWorkTimer=true
    , 
    afterConvoWorkMaxTime=<ACW_SECONDS>
    , optional 
    presenceStatusOnDecline
    , and 
    assignments/users
    for the resolved agents.
Elements are emitted in strict XSD order. Idempotency comes from the Metadata API 
files[].state
per component (
Unchanged
→reused, 
Changed
→updated, 
Created
→created); the deploy runs 
--async
and polls to a terminal state.
deploy-and-report.sh
会将两个组件实例化到临时DX项目中，并通过一次调用完成部署：
  1. PresenceDeclineReason:<reason>
    —— 拒绝原因（仅包含标签）。
  2. PresenceUserConfig:<config>
    —— 包含容量+标签、
    enableAutoAccept=false
    、
    enableDecline=true
    、
    enableDeclineReason=true
    、
    declineReasons=<reason>
    、
    hasAfterConvoWorkTimer=true
    、
    afterConvoWorkMaxTime=<ACW_SECONDS>
    、可选的
    presenceStatusOnDecline
    ，以及为解析后的座席设置的
    assignments/users
    。
元素严格按照XSD顺序生成。幂等性来自Metadata API针对每个组件的
files[].state
（
Unchanged
→复用，
Changed
→更新，
Created
→创建）；部署以
--async
方式运行，并轮询直至进入终端状态。

Behavior

Behavior

Whole-record + consistent. The record is always emitted with the validator-safe combination, so a re-deploy is a clean no-op rather than a field diff that could trip a cross-field rule.
Non-destructive. Only the named config and decline reason are written; other presence configs and decline reasons on the org are never touched. Assignments are declared for the resolved agents; the skill does not remove users it did not add (a redeploy declares the full assignment set for this config).
整记录+一致性：生成的记录始终符合验证规则要求的组合，因此重新部署会是无操作的干净执行，而非可能触发跨字段规则的字段差异更新。
非破坏性：仅写入指定的配置和拒绝原因；组织中的其他在线状态配置和拒绝原因绝不会被修改。会为解析后的座席声明分配关系；本技能不会移除未添加的用户（重新部署会声明此配置的完整分配集合）。

Output contract

Output contract

A single JSON object: 
status
∈ 
created
| 
updated
| 
reused
| 
blocked
, 
config
(
{developer_name, label, capacity, acw_seconds, state}
), 
decline_reason
(
{developer_name, label, state}
), 
assigned_usernames
, 
deploy_id
, 
manual_actions
, 
blocking_issue
.
返回单个JSON对象：
status
∈ 
created
| 
updated
| 
reused
| 
blocked
，
config
（
{developer_name, label, capacity, acw_seconds, state}
），
decline_reason
（
{developer_name, label, state}
），
assigned_usernames
，
deploy_id
，
manual_actions
，
blocking_issue
。

Limitations

Limitations

  • One presence configuration per invocation.
  • Encodes the decline+ACW rep profile from the steel thread; other field combinations require forking the XML template.
  • Does not set the channel-level After-Conversation-Work timer on a 
    ServiceChannel
    (a separate concern), deploy 
    ServicePresenceStatus
    , or grant status access via permission set.
  • 每次调用仅能部署一个在线状态配置。
  • 封装了steel thread中的拒绝+ACW客服配置；其他字段组合需要修改XML模板。
  • 不支持在
    ServiceChannel
    上设置渠道级对话后工作（After-Conversation-Work）计时器（这是单独的事项）、部署
    ServicePresenceStatus
    ，或通过权限集授予状态访问权限。

References

References

FileWhen to read
references/api-notes.md
PresenceUserConfig cross-field validators, XSD element order, decline-reason packaging, and ACW field pairing
scripts/tests/_bootstrap.py
Test bootstrap loaded by the contract suite to locate the skill root and run its shell entry point
scripts/tests/test_presence_user_config_contracts.py
Run after changing the deployment script to verify guard, whole-record, membership, and output contracts
文件阅读场景
references/api-notes.md
PresenceUserConfig跨字段验证规则、XSD元素顺序、拒绝原因打包方式以及ACW字段配对规则
scripts/tests/_bootstrap.py
契约测试套件加载的测试引导程序，用于定位技能根目录并运行其Shell入口点
scripts/tests/test_presence_user_config_contracts.py
修改部署脚本后运行，用于验证防护机制、整记录写入、成员分配和输出契约