Back to Details

sf-vlocity-build-deploy

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

sf-vlocity-build-deploy: Vlocity Build DataPack Deployment

sf-vlocity-build-deploy：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 DataPacks的导出/部署工作流、清单驱动部署、故障排查，以及CI/CD流程编排。

When This Skill Owns the Task

本技能适用场景

Use 
sf-vlocity-build-deploy
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
    -> sf-deploy
  • building OmniScripts, FlexCards, IPs, or Data Mappers -> 
    sf-industry-commoncore-*
  • designing Product2 EPC bundles -> sf-industry-cme-epc-model
  • writing Apex/LWC code -> sf-apex, sf-lwc
当工作涉及以下内容时使用
sf-vlocity-build-deploy
：
  • vlocity packDeploy
    、
    packRetry
    、
    packContinue
    、
    packExport
    、
    packGetDiffs
    、
    validateLocalData
    命令
  • DataPack任务文件设计（
    projectPath
    、
    expansionPath
    、
    manifest
    、
    queries
    配置）
  • 跨组织DataPack迁移与重试循环处理
  • 排查DataPack依赖、匹配键、GlobalKey相关问题
以下场景请转至对应技能处理：
  • 使用
    sf project deploy
    部署标准元数据 → sf-deploy
  • 开发OmniScripts、FlexCards、IP、数据映射器 → 
    sf-industry-commoncore-*
  • 设计Product2 EPC套餐 → sf-industry-cme-epc-model
  • 编写Apex/LWC代码 → sf-apex、sf-lwc

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

High-Signal Failure Patterns

常见故障模式

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 DataPackssf-deployMetadata API workflows
OmniStudio component authoring
sf-industry-commoncore-*
build artifacts before deploy
EPC product and offer payload authoringsf-industry-cme-epc-modelProduct2/DataPack model quality
Apex trigger/log error diagnosissf-debug, sf-apexautomation-side root-cause fixes
需求转交技能原因
DataPacks之外的元数据部署sf-deploy元数据API工作流
OmniStudio组件开发
sf-industry-commoncore-*
部署前的制品构建
EPC产品与Offer载荷开发sf-industry-cme-epc-modelProduct2/DataPack模型质量
Apex触发器/日志错误诊断sf-debug、sf-apex自动化侧根因修复

Reference Map

参考索引

Start here

入门参考

  • references/job-file-template.md
  • references/troubleshooting-matrix.md
  • examples/business-internet-plus-bundle/TRANSCRIPT.md
  • examples/business-internet-plus-bundle-deploy/TRANSCRIPT.md
  • references/job-file-template.md
  • references/troubleshooting-matrix.md
  • examples/business-internet-plus-bundle/TRANSCRIPT.md
  • examples/business-internet-plus-bundle-deploy/TRANSCRIPT.md

External reference

外部参考

Completion Format

完成输出格式

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>
text
DataPack目标：<export / deploy / retry / diff / ci-cd>
源组织：<alias or N/A>
目标组织：<alias or N/A>
范围：<job file + manifest/key/full>
结果：<passed / failed / partial>
关键发现：<errors, dependencies, retries, diffs>
下一步：<safe follow-up action>