omnistudio-datapacks-deploy

omnistudio-datapacks-deploy：Vlocity Build DataPack 部署

当用户需要编排 Vlocity DataPack 部署时，使用此技能：导出/部署工作流、由清单驱动的部署、失败排查，以及 OmniStudio/Industries DataPack 的 CI/CD 排序。

---

范围

在以下工作中使用 omnistudio-datapacks-deploy：

• vlocity packDeploy、packRetry、packContinue、packExport、packGetDiffs、validateLocalData
• DataPack 作业文件设计（projectPath、expansionPath、manifest、queries）
• 组织间 DataPack 迁移和重试循环
• 排查 DataPack 依赖项、匹配键和 GlobalKey 问题

以下情况应委派给其他技能：

• 使用 sf project deploy 部署标准元数据 -> platform-metadata-deploy
• 构建 OmniScripts、FlexCards、IP 或 Data Mapper -> omnistudio-*-build
• 设计 Product2 EPC 套件 -> omnistudio-epc-catalog-generate
• 编写 Apex/LWC 代码 -> platform-apex-generate、experience-lwc-generate

---

关键操作规则

• 使用 Vlocity Build (vlocity) 命令处理 DataPack，而非 sf project deploy。
• 如可用，优先使用 Salesforce CLI 身份验证集成（-sfdx.username <alias>），而非用户名/密码文件。
• 完整部署前始终运行预部署质量门禁：
  1. validateLocalData
  2. 可选：packGetDiffs
  3. 然后运行 packDeploy
• 当错误数量持续减少时，重复使用 packRetry；如果重试不再改善结果，则停止。
• 确保源组织和目标组织的匹配键策略与 GlobalKey 完整性保持一致。

---

首先收集所需上下文

询问或推断：

• 源组织和目标组织别名
• 作业文件路径和 DataPack 项目路径
• 部署范围（完整项目、清单子集或特定 -key）
• 操作类型是导出、部署、重试、继续还是仅查看差异
• 命名空间模型（%vlocity_namespace%、vlocity_cmt 或 core）
• 已知限制（新沙箱引导、触发器行为、匹配键自定义）

预检：

vlocity help
sf org list
sf org display --target-org <alias> --json
test -f <job-file>.yaml

---

推荐工作流

1. 确保工具已就绪

npm install --global vlocity
vlocity help

2. 在本地验证项目数据

vlocity -sfdx.username <source-alias> -job <job-file>.yaml validateLocalData

仅在用户明确要求且说明影响后，才使用 --fixLocalGlobalKeys。

3. 从源组织导出（需要时）

vlocity -sfdx.username <source-alias> -job <job-file>.yaml packExport
vlocity -sfdx.username <source-alias> -job <job-file>.yaml packRetry

4. 部署到目标组织

vlocity -sfdx.username <target-alias> -job <job-file>.yaml packDeploy
vlocity -sfdx.username <target-alias> -job <job-file>.yaml packRetry

5. 继续被中断的作业

vlocity -sfdx.username <target-alias> -job <job-file>.yaml packContinue

6. 验证部署后的状态一致性

vlocity -sfdx.username <target-alias> -job <job-file>.yaml packGetDiffs

作业文件模板：references/job-file-template.md

---

注意事项

错误 / 现象	可能原因	默认修复方向
No match found for ...	目标组织缺少依赖项	加入缺失的 DataPack 键并重新部署
Duplicate Results found for ... GlobalKey	目标组织中存在重复记录	清理重复项并重新运行部署
Multiple Imported Records ... same Salesforce Record	源组织中存在重复的匹配键记录	在源组织中删除重复项并重新导出
No Configuration Found	DataPack 设置已过期	运行 packUpdateSettings 或启用 autoUpdateSettings
Some records were not processed	设置不匹配 / 依赖状态不完整	刷新两个组织的设置，然后重试
SASS / 模板编译失败	缺少所引用的 UI 模板资源	先导出/部署所引用的模板依赖项

详细矩阵：references/troubleshooting-matrix.md

---

CI/CD 指南

默认流水线结构：

1. 对组织进行身份验证（sf org login ...）
2. 验证本地 DataPack 完整性（validateLocalData）
3. 导出变更范围（packExport 或由清单驱动的导出）
4. 部署（packDeploy）
5. 重试循环（packRetry），直至稳定
6. 比较（packGetDiffs）并发布部署报告

要优化增量部署，请使用作业文件选项，例如：

• gitCheck: true
• gitCheckKey: <folder>
• manifest，用于确定性地控制范围

---

跨技能集成

需求	委派给	原因
在 DataPack 之外部署元数据	platform-metadata-deploy	Metadata API 工作流
创作 OmniStudio 组件	omnistudio-*-build	在部署前构建制品
创作 EPC 产品和报价负载	omnistudio-epc-catalog-generate	Product2/DataPack 模型质量
诊断 Apex 触发器／日志错误	platform-apex-logs-debug、platform-apex-generate	修复自动化侧的根本原因

---

输出要求

完成 DataPack 操作后，提供一个完成信息块：

DataPack goal: <export / deploy / retry / diff / ci-cd>
Source org: <alias or N/A>
Target org: <alias or N/A>
Scope: <job file + manifest/key/full>
Result: <passed / failed / partial>
Key findings: <errors, dependencies, retries, diffs>
Next step: <safe follow-up action>

---

参考文件索引

文件	何时阅读
references/job-file-template.md	在提供作业文件结构建议前阅读——将其作为基准配置参考
references/troubleshooting-matrix.md	用户报告部署失败时阅读——用于诊断 DataPack 错误并应用修复指引
examples/business-internet-plus-bundle/TRANSCRIPT.md	Product2 套餐验证规划与执行示例
examples/business-internet-plus-bundle/deploy-business-internet-plus-bundle.yaml	限定范围运行 validateLocalData 的作业文件示例
examples/business-internet-plus-bundle-deploy/TRANSCRIPT.md	完整部署周期示例，包括 packDeploy 和 packRetry 的结果
examples/business-internet-plus-bundle-deploy/deploy-business-internet-plus-bundle.yaml	通过清单指定目标的分阶段部署作业文件示例