mcpField
S
service-omni-base-settings-configure

service-omni-base-settings-configure

github.com/forcedotcom其他1.1k88 次安装1 天前更新
代码仓库

关于 service-omni-base-settings-configure

此 Salesforce skill 通过受保护的 Metadata API 部署启用五项 OmniChannelSettings 开关。它会先检查状态，提供只读计划模式，并提示仍需手动设置的登录行为选项。

主要功能

  1. 01部署前检查开关状态
  2. 02启用五项 OmniChannelSettings 开关
  3. 03提供只读计划模式
  4. 04限制可写入的组织
  5. 05部署后重新验证设置

适用场景

  1. 01为后续 Omni 配置准备组织
  2. 02只检查必需设置而不做更改

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/forcedotcom/sf-skills --skill service-omni-base-settings-configure

安装后在 Claude Code 中输入/service-omni-base-settings-configure确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

assets/
package.xml
sfdx-project.json
assets/force-app/main/default/settings/
OmniChannel.settings-meta.xml
references/
api-notes.md
scripts/
configure-and-report.sh
detect-existing.sh

详细介绍

service-omni-base-settings-configure

通过一次 Metadata API 部署启用五个 OmniChannelSettings 布尔值（enableOmniChannel、enableOmniAutoLoginPrompt、enableOmniSecondaryRoutingPriority、enableOmniSkillsRouting、enableOmniStatusCapModel）。如果没有 enableOmniChannel=true，后续的队列、在线状态和路由流等都无法正常工作，因此这必须是 Omni 设置流程中的第一项写入操作。该技能会先探测，只有在某个开关为 false 或缺失时才会部署。

输入

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。

前置条件与安全

  • 目标组织已通过 sf CLI 完成身份验证（使用 My Domain URL，而非 .lightning.force.com），具备 Service Cloud 许可证，且 sf CLI ≥ 2.139.6。
  • 生产环境防护： 写入器将 safe_to_write 计算为 IsSandbox OR TrialExpirationDate != null OR OrganizationType 属于 {Developer Edition, Base Edition}；如果结果为 false，则禁止写入且不提供覆盖选项。这允许 CDO（IsSandbox=false 且 TrialExpirationDate 非 null）；不要将其弱化为仅检查 IsSandbox。

运行

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 指定设置文件；其模板在运行时绝不修改，因此该技能可重复执行，也不会仅因本地源跟踪状态干净而报告 "No local changes to deploy"。

行为

整份文档写入。 Settings 是整份文档的元数据类型——Metadata API 不接受部分更新，因此该技能始终部署完整文件，而不是 PATCH 单个开关。

登录行为缺口。 Omni 登录行为单选项（Setup → Omni-Channel Settings → "Define login behavior when an agent opens a new window/tab"）在 v66 中没有公开 API。报告始终会显示其点击路径——即使是无操作的 reused 运行也是如此——因此，“无需执行任何操作”的结果不会掩盖唯一需要手动执行的操作。enableOmniAutoLoginPrompt 仍会正常部署（其他 Omni 功能可能在内部依赖它），但不会控制该单选项。

失败时阻止通过验证。 部署后，该技能会重新探测，并要求五个开关全部为 true；如果部署报告成功但更改未生效（组织级限制较少见），则会阻止操作，而不是报告成功。

输出约定

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 — 五个开关原本都为 true；未执行部署。
  • action_needed — 计划模式发现有禁用的开关；未执行部署。
  • blocked — safe_to_write=false、部署失败或状态为 SucceededPartial，或者重新探测仍显示有开关为 false。

对于非阻止状态的报告，manual_actions 始终包含登录行为差异条目；对于 reused/action_needed，deploy_id 为 null；只有当 status: blocked 时，blocking_issue 才会说明失败原因。

限制

  • 仅配置 OmniChannelSettings，并始终将五个开关都设为 true——其他类型的 Settings 由 platform-metadata-deploy 负责。
  • 无法切换登录行为单选项（v66 没有公共 API）——此工具只会显示点击路径。

参考资料

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

评论

支持 Markdown