omnistudio-datapacks-deploy

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
• building OmniScripts, FlexCards, IPs, or Data Mappers -> omnistudio-*-build
• designing Product2 EPC bundles -> omnistudio-epc-catalog-generate
• writing Apex/LWC code -> platform-apex-generate, experience-lwc-generate

---

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

---

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

---

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-deploy	Metadata API workflows
OmniStudio component authoring	omnistudio-*-build	build artifacts before deploy
EPC product and offer payload authoring	omnistudio-epc-catalog-generate	Product2/DataPack model quality
Apex trigger/log error diagnosis	platform-apex-logs-debug, platform-apex-generate	automation-side root-cause fixes

---

Output Expectations

After completing a DataPack operation, deliver a completion block:

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>

---

Reference File Index

File	When 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

---

omnistudio-datapacks-deploy

Salesforce Industries DataPack deployment automation using Vlocity Build. Export, validate, deploy, retry, and compare OmniStudio/Vlocity DataPacks with predictable workflow guardrails.

Features

• DataPack Deployment Workflow: Run packExport, packDeploy, packRetry, packContinue, and packGetDiffs
• Job File Guidance: Build deterministic projectPath, expansionPath, queries, and manifest job patterns
• Validation-First Operations: Gate deployment with validateLocalData and dependency checks
• Failure Triage: Diagnose matching-key, GlobalKey, dependency, and configuration drift failures
• CI/CD Patterns: Support manifest-driven and git-aware deployment sequencing

Usage

Invoke this skill when working with OmniStudio/Vlocity DataPack deployments:

Skill: omnistudio-datapacks-deploy
Request: "Deploy my OmniStudio DataPacks to UAT using Vlocity Build and include retry guidance."

Common Operations

Operation	Example Request
Export	"Export DataPacks from source org with this job file."
Validate local files	"Run pre-deploy validation and identify key issues."
Deploy	"Deploy DataPacks to target org using packDeploy."
Retry failures	"Run packRetry and summarize what remains."
Resume interrupted run	"Continue the failed deployment job."
Compare with target	"Run packGetDiffs and report drift."

Key Commands

# Validate local DataPack integrity
vlocity -sfdx.username [sourceAlias] -job [jobFile].yaml validateLocalData

# Export from source
vlocity -sfdx.username [sourceAlias] -job [jobFile].yaml packExport

# Deploy to target
vlocity -sfdx.username [targetAlias] -job [jobFile].yaml packDeploy

# Retry failed DataPacks
vlocity -sfdx.username [targetAlias] -job [jobFile].yaml packRetry

# Continue interrupted execution
vlocity -sfdx.username [targetAlias] -job [jobFile].yaml packContinue

# Compare local files to target org
vlocity -sfdx.username [targetAlias] -job [jobFile].yaml packGetDiffs

Best Practices

Rule	Details
Validate first	Run validateLocalData before deploy
Keep scope minimal	Prefer manifest/key-scoped deploys for safer rollouts
Retry intentionally	Use packRetry while error count is decreasing
Preserve key strategy	Keep matching keys and GlobalKeys consistent across orgs
Compare post-deploy	Run packGetDiffs to verify target parity

Cross-Skill Integration

Related Skill	When to Use
platform-metadata-deploy	Deploy non-DataPack Salesforce metadata with sf project deploy
omnistudio-omniscript-generate	Author OmniScripts before deployment
omnistudio-flexcard-generate	Build FlexCards before deployment
omnistudio-integration-procedure-generate	Build Integration Procedures before deployment
platform-apex-logs-debug	Investigate runtime/triggers/log failures surfaced during deploy

Documentation

• SKILL.md - Full DataPack deployment workflow and operating rules
• references/job-file-template.md - Baseline job file patterns
• references/troubleshooting-matrix.md - Common failures and fix directions
• examples/business-internet-plus-bundle/TRANSCRIPT.md - Validation planning/execution transcript and outcomes
• examples/business-internet-plus-bundle-deploy/TRANSCRIPT.md - Deployment execution transcript with packDeploy/packRetry results

Requirements

• Node.js 18+
• Vlocity Build CLI (npm install --global vlocity)
• Salesforce CLI v2 (for org auth and context)
• Source and target org access