deploying-omnistudio-datapacks

deploying-omnistudio-datapacks：Vlocity Build DataPack 部署

当用户需要协调 Vlocity DataPack 部署时使用此技能：导出/部署工作流、基于清单的部署、故障排查，以及 OmniStudio/Industries DataPack 的 CI/CD 顺序安排。

---

范围

以下工作适用 deploying-omnistudio-datapacks：

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

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

• 使用 sf project deploy 部署标准元数据 -> deploying-metadata
• 构建 OmniScripts、FlexCards、IPs 或 Data Mapper -> building-omnistudio-*
• 设计 Product2 EPC 产品包 -> modeling-omnistudio-epc-catalog
• 编写 Apex/LWC 代码 -> generating-apex、generating-lwc-components

---

关键操作规则

• 使用 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 或核心）
• 已知限制（新沙盒引导、触发器行为、匹配键自定义项）

预检：

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 之外部署元数据	deploying-metadata	Metadata API 工作流
OmniStudio 组件创作	building-omnistudio-*	在部署前构建制品
EPC 产品和报价有效负载创作	modeling-omnistudio-epc-catalog	Product2/DataPack 模型质量
Apex 触发器/日志错误诊断	debugging-apex-logs、generating-apex	修复自动化侧的根本原因

---

输出要求

完成 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	使用清单指定目标的分阶段部署作业文件示例