/omnistudio-datapacks-deploy

name: omnistudio-datapacks-deploy
description: "Salesforce Industries DataPack deployment automation using Vlocity Build. TRIGGER when: user deploys or validates OmniStudio/Vlocity DataPacks with vlocity commands (packDeploy/packRetry/packExport/packGetDiffs), sets up DataPack CI/CD pipelines, or troubleshoots DataPack migration errors. DO NOT TRIGGER when: deploying Salesforce metadata with sf project deploy (use platform-metadata-deploy), authoring OmniStudio artifacts (use omnistudio-*-build), or writing Apex/LWC business logic (use platform-apex-generate/experience-lwc-generate)."
metadata:
  cliTools:
    - tool: ["npm"]
      semver: ">=9.0.0"
    - tool: ["npx"]
      semver: ">=9.0.0"
    - tool: ["sf"]
      semver: ">=2.0.0"
    - tool: ["vlocity"]
      semver: ">=1.16.0"
  relatedSkills:
    - "experience-lwc-generate"
    - "omnistudio-epc-catalog-generate"
    - "omnistudio-flexcard-generate"
    - "omnistudio-integration-procedure-generate"
    - "omnistudio-omniscript-generate"
    - "platform-apex-generate"
    - "platform-apex-logs-debug"
    - "platform-metadata-deploy"
  version: "1.0"

omnistudio-datapacks-deploy: Vlocity Build DataPack Deployment

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.

---

Scope

Use `omnistudio-datapacks-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` -> [platform-metadata-deploy](../platform-metadata-deploy/SKILL.md)
• building OmniScripts, FlexCards, IPs, or Data Mappers -> `omnistudio-*-build`
• designing Product2 EPC bundles -> [omnistudio-epc-catalog-generate](../omnistudio-epc-catalog-generate/SKILL.md)
• writing Apex/LWC code -> [platform-apex-generate](../platform-apex-generate/SKILL.md), [experience-lwc-generate](../experience-lwc-generate/SKILL.md)

---

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.

---

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:

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

---

Recommended Workflow

1. Ensure tool readiness

npm install --global vlocity
vlocity help

2. Validate project data locally

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

Use `--fixLocalGlobalKeys` only when explicitly requested and after explaining impact.

3. Export from source (when needed)

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

4. Deploy to target

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

5. Continue interrupted jobs

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

6. Verify post-deploy parity

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

Job-file starter: [references/job-file-template.md](references/job-file-template.md)

---

Gotchas

| Error / symptom | Likely cause | Default fix direction | |---|---|---| | `No match found for ...` | missing dependency in target org | include missing DataPack key and redeploy | | `Duplicate Results found for ... GlobalKey` | duplicate records in target | clean duplicates and re-run deploy | | `Multiple Imported Records ... same Salesforce Record` | source duplicate matching-key records | remove duplicates in source and re-export | | `No Configuration Found` | outdated DataPack settings | run `packUpdateSettings` or enable `autoUpdateSettings` | | `Some records were not processed` | settings mismatch / partial dependency state | refresh settings both orgs, then retry | | SASS / template compile failures | missing referenced UI template assets | export/deploy referenced template dependencies first |

Detailed matrix: [references/troubleshooting-matrix.md](references/troubleshooting-matrix.md)

---

CI/CD Guidance

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

---

Cross-Skill Integration

| Need | Delegate to | Reason | |---|---|---| | metadata deploy outside DataPacks | [platform-metadata-dep