Back to Details

deploying-omnistudio-datapacks

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

deploying-omnistudio-datapacks: Vlocity Build DataPack Deployment

deploying-omnistudio-datapacks：Vlocity Build DataPack部署

Use this skill when the user needs Vlocity DataPack deployment orchestration: export/deploy workflow, manifest-driven deploys, failure triage, and CI/CD sequencing for OmniStudio/Industries DataPacks.
当用户需要Vlocity DataPack部署编排时使用本技能：包括OmniStudio/Industries DataPack的导出/部署工作流、清单驱动部署、故障排查以及CI/CD流程编排。

Scope

适用范围

Use 
deploying-omnistudio-datapacks
when work involves:
  • vlocity packDeploy
    , 
    packRetry
    , 
    packContinue
    , 
    packExport
    , 
    packGetDiffs
    , 
    validateLocalData
  • DataPack job-file design (
    projectPath
    , 
    expansionPath
    , 
    manifest
    , 
    queries
    )
  • org-to-org DataPack migration and retry loops
  • troubleshooting DataPack dependency, matching-key, and GlobalKey issues
Delegate elsewhere when the user is:
  • deploying standard metadata with 
    sf project deploy
    -> deploying-metadata
  • building OmniScripts, FlexCards, IPs, or Data Mappers -> 
    building-omnistudio-*
  • designing Product2 EPC bundles -> modeling-omnistudio-epc-catalog
  • writing Apex/LWC code -> generating-apex, generating-lwc-components
当工作涉及以下内容时，使用
deploying-omnistudio-datapacks
：
  • vlocity packDeploy
    、
    packRetry
    、
    packContinue
    、
    packExport
    、
    packGetDiffs
    、
    validateLocalData
    命令
  • DataPack作业文件设计（
    projectPath
    、
    expansionPath
    、
    manifest
    、
    queries
    ）
  • 组织间DataPack迁移与重试循环
  • 排查DataPack依赖、匹配键和GlobalKey问题
当用户进行以下操作时，请转至其他技能：
  • 使用
    sf project deploy
    部署标准元数据 -> deploying-metadata
  • 构建OmniScript、FlexCards、IP或数据映射器 -> 
    building-omnistudio-*
  • 设计Product2 EPC捆绑包 -> modeling-omnistudio-epc-catalog
  • 编写Apex/LWC代码 -> generating-apex、generating-lwc-components

Critical Operating Rules

核心操作规则

  • Use Vlocity Build (
    vlocity
    )     commands for DataPacks, not 
    sf project deploy
    .
  • Prefer Salesforce CLI auth integration (
    -sfdx.username <alias>
    ) over username/password files when available.
  • Always run a pre-deploy quality gate before full deploy: 
    1. validateLocalData
    2. optional 
      packGetDiffs
    3. then 
      packDeploy
  • Use 
    packRetry
    repeatedly when error counts are dropping; stop when retries no longer improve results.
  • Keep matching-key strategy and GlobalKey integrity consistent across source and target orgs.
  • 对DataPack使用**Vlocity Build（
    vlocity
    ）**命令，而非
    sf project deploy
    。
  • 若可用，优先使用Salesforce CLI身份验证集成（
    -sfdx.username <alias>
    ），而非用户名/密码文件。
  • 完整部署前必须运行部署前质量检查： 
    1. validateLocalData
    2. 可选
      packGetDiffs
    3. 然后执行
      packDeploy
  • 当错误数量下降时，重复使用
    packRetry
    ；当重试不再改善结果时停止。
  • 在源组织和目标组织间保持匹配键策略和GlobalKey完整性一致。

Required Context to Gather First

需优先收集的上下文信息

Ask for or infer:
  • source org and target org aliases
  • job file path and DataPack project path
  • deployment scope (full project, manifest subset, or specific 
    -key
    )
  • whether this is export, deploy, retry, continue, or diff-only
  • namespace model (
    %vlocity_namespace%
    , 
    vlocity_cmt
    , or core)
  • known constraints (new sandbox bootstrap, trigger behavior, matching key customizations)
Preflight checks:
bash
vlocity help
sf org list
sf org display --target-org <alias> --json
test -f <job-file>.yaml
询问或推断以下信息：
  • 源组织和目标组织别名
  • 作业文件路径和DataPack项目路径
  • 部署范围（完整项目、清单子集或特定
    -key
    ）
  • 操作类型（导出、部署、重试、继续或仅对比差异）
  • 命名空间模型（
    %vlocity_namespace%
    、
    vlocity_cmt
    或核心）
  • 已知约束（新沙箱初始化、触发器行为、匹配键自定义）
预检检查：
bash
vlocity help
sf org list
sf org display --target-org <alias> --json
test -f <job-file>.yaml

Recommended Workflow

推荐工作流

1. Ensure tool readiness

1. 确保工具就绪

bash
npm install --global vlocity
vlocity help
bash
npm install --global vlocity
vlocity help

2. Validate project data locally

2. 本地验证项目数据

bash
vlocity -sfdx.username <source-alias> -job <job-file>.yaml validateLocalData
Use 
--fixLocalGlobalKeys
only when explicitly requested and after explaining impact.
bash
vlocity -sfdx.username <source-alias> -job <job-file>.yaml validateLocalData
仅在明确请求并解释影响后，使用
--fixLocalGlobalKeys
。

3. Export from source (when needed)

3. 从源组织导出（按需）

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

4. Deploy to target

4. 部署至目标组织

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

5. Continue interrupted jobs

5. 继续中断的作业

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

6. Verify post-deploy parity

6. 验证部署后一致性

bash
vlocity -sfdx.username <target-alias> -job <job-file>.yaml packGetDiffs
Job-file starter: references/job-file-template.md
bash
vlocity -sfdx.username <target-alias> -job <job-file>.yaml packGetDiffs
作业文件模板：references/job-file-template.md

Gotchas

常见陷阱

Error / symptomLikely causeDefault fix direction
No match found for ...
missing dependency in target orginclude missing DataPack key and redeploy
Duplicate Results found for ... GlobalKey
duplicate records in targetclean duplicates and re-run deploy
Multiple Imported Records ... same Salesforce Record
source duplicate matching-key recordsremove duplicates in source and re-export
No Configuration Found
outdated DataPack settingsrun 
packUpdateSettings
or enable 
autoUpdateSettings
Some records were not processed
settings mismatch / partial dependency staterefresh settings both orgs, then retry
SASS / template compile failuresmissing referenced UI template assetsexport/deploy referenced template dependencies first
Detailed matrix: references/troubleshooting-matrix.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 Guidance

CI/CD指导

Default pipeline shape:
  1. authenticate orgs (
    sf org login ...
    )
  2. validate local DataPack integrity (
    validateLocalData
    )
  3. export changed scope (
    packExport
    or manifest-driven export)
  4. deploy (
    packDeploy
    )
  5. retry loop (
    packRetry
    ) until stable
  6. compare (
    packGetDiffs
    ) and publish deployment report
For incremental deploy optimization, use job-file options such as:
  • gitCheck: true
  • gitCheckKey: <folder>
  • manifest
    for deterministic scope control
默认流水线架构：
  1. 组织身份验证（
    sf org login ...
    ）
  2. 验证本地DataPack完整性（
    validateLocalData
    ）
  3. 导出变更范围（
    packExport
    或清单驱动导出）
  4. 部署（
    packDeploy
    ）
  5. 重试循环（
    packRetry
    ）直至稳定
  6. 对比差异（
    packGetDiffs
    ）并发布部署报告
为优化增量部署，可使用作业文件选项，例如：
  • gitCheck: true
  • gitCheckKey: <folder>
  • manifest
    用于确定性范围控制

Cross-Skill Integration

跨技能集成

NeedDelegate toReason
metadata deploy outside DataPacksdeploying-metadataMetadata API workflows
OmniStudio component authoring
building-omnistudio-*
build artifacts before deploy
EPC product and offer payload authoringmodeling-omnistudio-epc-catalogProduct2/DataPack model quality
Apex trigger/log error diagnosisdebugging-apex-logs, generating-apexautomation-side root-cause fixes
需求转至技能原因
DataPack之外的元数据部署deploying-metadata元数据API工作流
OmniStudio组件编写
building-omnistudio-*
部署前构建工件
EPC产品与报价负载编写modeling-omnistudio-epc-catalogProduct2/DataPack模型质量
Apex触发器/日志错误诊断debugging-apex-logs、generating-apex自动化侧根因修复

Output Expectations

输出预期

After completing a DataPack operation, deliver a completion block:
text
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>
完成DataPack操作后，提供完成报告：
text
DataPack目标：<导出/部署/重试/差异对比/CI-CD>
源组织：<别名或无>
目标组织：<别名或无>
范围：<作业文件 + 清单/键/完整项目>
结果：<通过/失败/部分完成>
关键发现：<错误、依赖项、重试情况、差异>
下一步：<安全跟进操作>

Reference File Index

参考文件索引

FileWhen to read
references/job-file-template.md
Before advising on job file structure — load as baseline configuration reference
references/troubleshooting-matrix.md
When user reports deploy failures — load to diagnose DataPack errors and apply fix directions
examples/business-internet-plus-bundle/TRANSCRIPT.md
Example of validation planning and execution for a Product2 bundle
examples/business-internet-plus-bundle/deploy-business-internet-plus-bundle.yaml
Example job file for scope-limited 
validateLocalData
run
examples/business-internet-plus-bundle-deploy/TRANSCRIPT.md
Example of full deploy cycle including 
packDeploy
and 
packRetry
outcomes
examples/business-internet-plus-bundle-deploy/deploy-business-internet-plus-bundle.yaml
Example job file for staged deployment with manifest targeting
文件阅读时机
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
清单定位的分阶段部署示例作业文件