Deploying Omnistudio Datapacks

deploying-omnistudio-datapacks: 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 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

---

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

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

---

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

Credits & Acknowledgments

This skill is based on practical OmniStudio/Vlocity DataPack deployment workflows and the Vlocity Build command model.

---

Deployment Transcript: Business Internet Plus Bundle

This transcript captures the skills used plus the planning and execution process for deploying business-internet-plus-bundle with Vlocity Build.

---

Task Summary

Deploy the Business Internet Plus Product2 bundle DataPack and document the end-to-end process in deploying-omnistudio-datapacks/examples.

---

Skills Used

1) deploying-omnistudio-datapacks (Primary)

Why used: The task is DataPack deployment orchestration with Vlocity Build commands (validateLocalData, packDeploy, packRetry) and failure triage.

Applied guidance:

• Validate-first execution (validateLocalData before deployment).
• Deterministic job file (projectPath, expansionPath, manifest) for reproducible scope.
• Retry loop and failure interpretation.

2) modeling-omnistudio-epc-catalog (Supporting)

Why used: The deployment target is an EPC Product2 offer bundle sample with Product Child Item dependencies and companion artifacts.

Applied guidance:

• Confirmed Product2 offer markers and companion file consistency.
• Preserved %vlocity_namespace% placeholders and stable GlobalKey references.

3) deploying-metadata (Supporting preflight pattern)

Why used: Reused deployment preflight discipline for target org/tooling readiness and concise completion reporting.

---

Planning Process (Executed)

1. Confirm where the source bundle artifacts were authored. 2. Stage those artifacts into a standard Vlocity expansion path under vlocity/Product2/<global-key>/. 3. Build a deterministic deploy job file in this example folder. 4. Run pre-deploy validation (validateLocalData). 5. Run actual deployment (packDeploy). 6. Run retry (packRetry) to confirm whether the failure is transient or dependency-blocking. 7. Capture findings and next safe action.

---

Execution Details

A) Staging for deploy

Source payload location:

• skills/modeling-omnistudio-epc-catalog/examples/business-internet-plus-bundle

Deploy staging location:

• vlocity/Product2/9f1d3c4a-8e5b-4d71-9a2d-f6b719a90101

Staged files include:

• Business-Internet-Plus_DataPack.json
• Business-Internet-Plus_AttributeAssignments.json
• Business-Internet-Plus_ProductChildItems.json
• Business-Internet-Plus_PricebookEntries.json
• Business-Internet-Plus_PriceListEntries.json
• Business-Internet-Plus_ObjectFieldAttributes.json
• Business-Internet-Plus_OrchestrationScenarios.json
• Business-Internet-Plus_DecompositionRelationships.json
• Business-Internet-Plus_CompiledAttributeOverrides.json
• Business-Internet-Plus_OverrideDefinitions.json
• Business-Internet-Plus_ParentKeys.json

B) Job file used

• skills/deploying-omnistudio-datapacks/examples/business-internet-plus-bundle-deploy/deploy-business-internet-plus-bundle.yaml

Key settings:

• projectPath: .
• expansionPath: vlocity
• manifest: Product2/9f1d3c4a-8e5b-4d71-9a2d-f6b719a90101

C) Commands executed

npx --yes vlocity -sfdx.username sample-uat -job "skills/deploying-omnistudio-datapacks/examples/business-internet-plus-bundle-deploy/deploy-business-internet-plus-bundle.yaml" validateLocalData

npx --yes vlocity -sfdx.username sample-uat -job "skills/deploying-omnistudio-datapacks/examples/business-internet-plus-bundle-deploy/deploy-business-internet-plus-bundle.yaml" packDeploy

npx --yes vlocity -sfdx.username sample-uat -job "skills/deploying-omnistudio-datapacks/examples/business-internet-plus-bundle-deploy/deploy-business-internet-plus-bundle.yaml" packRetry

D) Command outcomes

validateLocalData:

• Success (1 Completed)

packDeploy:

• Auto-settings migration phase completed successfully.
• Bundle deploy failed with dependency error:
• This DataPack has a reference to another object which was not found -- Product2/21e9dce1-4f89-4f99-a7b2-9cb5d6332101

packRetry:

• Failed with the same missing reference error.

---

Root Cause

The bundle references child Product2 DataPacks that are not currently present in local expansion scope and/or target org at deploy time.

Missing child Product2 keys confirmed absent from local vlocity/Product2:

• 21e9dce1-4f89-4f99-a7b2-9cb5d6332101 (Managed Router)
• 43f2fd94-6114-449b-a1b4-b8dd7238b202 (Internet Security Suite)
• 64a06b24-1135-4f2e-95a1-3a5f5822c303 (Static IP Add-On)

---

Completion Block

DataPack goal: deploy
Source org: N/A (local staged payload)
Target org: sample-uat
Scope: Product2/9f1d3c4a-8e5b-4d71-9a2d-f6b719a90101
Result: failed (dependency missing)
Key findings:
- validateLocalData passed (1 completed)
- packDeploy failed: missing referenced child Product2
- packRetry failed with same error
Next step:
- Stage/deploy the three child Product2 DataPacks first (or include them in manifest), then rerun packDeploy and packRetry.

Validation Transcript: Business Internet Plus Bundle Deployment

This transcript captures the skills used and the planning/execution process to validate deployment readiness for the business-internet-plus-bundle sample.

---

Task Summary

Validate deployment for the Business Internet Plus bundle and document the process in a new examples folder under deploying-omnistudio-datapacks.

---

Skills Used

1) deploying-omnistudio-datapacks (Primary)

Why used: The task is Vlocity Build deployment validation for DataPacks (validateLocalData, deployment preflight, and scope verification).

Applied from skill guidance:

• Validate-first workflow (validateLocalData before deploy).
• Required context checks (tooling readiness, org auth, deterministic scope).
• Job-file driven validation with explicit manifest targeting.

2) deploying-metadata (Supporting)

Why used: Deployment preflight practices overlap with org readiness checks.

Applied from skill guidance:

• Confirm CLI and org context before execution.
• Capture result and safe next action in a completion block.

3) modeling-omnistudio-epc-catalog (Supporting)

Why used: The target bundle payload was generated as an EPC Product2 offer bundle sample, so EPC-specific structure and guardrails were validated before deployment checks.

Applied from skill guidance:

• Confirm offer markers (SpecificationType=Offer, SpecificationSubType=Bundle).
• Confirm root PCI + child PCI composition.
• Confirm companion bundle artifacts and GlobalKey consistency.

---

Planning Process (Executed)

1. Locate the business-internet-plus-bundle payload and confirm all companion JSON artifacts exist. 2. Run preflight checks for deployment tooling:

• vlocity CLI availability.
• Salesforce org auth context for target alias.

3. Run file-level integrity checks:

• JSON parse for all bundle artifacts.
• Product2 + PCI + attribute consistency checks.

4. Create a deterministic Vlocity Build job file in this example folder for reproducible validation. 5. Execute validateLocalData against the bundle scope and record outcome. 6. Summarize result, findings, and safe next actions.

---

Execution Log

A) Bundle discovery

• Located bundle payload at:
• skills/modeling-omnistudio-epc-catalog/examples/business-internet-plus-bundle
• Confirmed 11 companion JSON files exist (DataPack, AttributeAssignments, ProductChildItems, pricing files, orchestration/decomposition files, overrides, and parent keys).

B) Tooling and org preflight

• vlocity global binary check: not installed globally (command not found).
• npx vlocity check: available (Vlocity Build v1.17.21).
• sf org list --json: org context available; target alias sample-uat is connected.

C) File-level integrity validation

Local JSON validation checks passed:

• Missing files: 0
• JSON parse errors: 0
• Product identity checks: name and product code match expected values.
• Offer checks: SpecificationType=Offer and SpecificationSubType=Bundle.
• Composition checks: 1 root PCI and 3 child PCI records.
• Attribute checks: 3 attribute assignment records.
• Key integrity checks: PCI parent references match Product2 GlobalKey.

D) Vlocity validateLocalData execution

Job file used:

• skills/deploying-omnistudio-datapacks/examples/business-internet-plus-bundle/deploy-business-internet-plus-bundle.yaml

Command:

npx --yes vlocity -sfdx.username sample-uat -job "skills/deploying-omnistudio-datapacks/examples/business-internet-plus-bundle/deploy-business-internet-plus-bundle.yaml" validateLocalData

Result:

• ValidateLocalData success: 0 Completed

Interpretation:

• Validation command executed successfully.
• 0 Completed indicates no DataPack records were processed for this scope layout.
• This is consistent with the sample payload being stored as a documentation/example artifact rather than a standard vlocity/ expansion deployment path.

---

Validation Outcome

DataPack goal: validate deployment readiness
Source org: N/A
Target org: sample-uat
Scope: deploy-business-internet-plus-bundle.yaml + Product2/9f1d3c4a-8e5b-4d71-9a2d-f6b719a90101
Result: partial
Key findings:
- Bundle JSON payload is internally consistent and structurally valid.
- Vlocity validateLocalData ran successfully but processed 0 DataPacks in current example-folder scope.
Next step:
- Stage the bundle into a standard Vlocity expansion path (for example under `vlocity/Product2/<global-key>/`) and rerun `validateLocalData`, then `packDeploy` and `packGetDiffs`.

deploying-omnistudio-datapacks

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: deploying-omnistudio-datapacks
Request: "Deploy my OmniStudio DataPacks to UAT using Vlocity Build and include retry guidance."

Common Operations

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

Cross-Skill Integration

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

Vlocity Build Job File Template

Use this as a baseline and keep only settings you need to override.

projectPath: .
expansionPath: vlocity

# Optional: narrow export scope
queries:
  - OmniScript
  - IntegrationProcedure
  - DataRaptor
  - FlexCard

# Optional: deterministic targeted scope
# manifest:
#   - Product2/<global-key>
#   - OmniScript/<type>_<subtype>_<language>

# Optional runtime controls
autoUpdateSettings: true
defaultMaxParallel: 1
supportHeadersOnly: true
gitCheck: false

Common command patterns

# Export
vlocity -sfdx.username <source> -job <job>.yaml packExport

# Deploy
vlocity -sfdx.username <target> -job <job>.yaml packDeploy

# Retry
vlocity -sfdx.username <target> -job <job>.yaml packRetry

# Continue interrupted
vlocity -sfdx.username <target> -job <job>.yaml packContinue

Vlocity Build Troubleshooting Matrix

Retry strategy

1. Run packRetry. 2. Check if error count decreases. 3. Repeat until error count plateaus. 4. Fix root data/config issue before further retries.

Data hygiene checks

vlocity -sfdx.username <org> -job <job>.yaml validateLocalData
vlocity -sfdx.username <org> -job <job>.yaml packGetDiffs