vlocity-to-native-omnistudio-migration

# Vlocity to Native OmniStudio Migration

This skill activates when the work involves transitioning an org from a Vlocity managed package deployment (vlocity_ins, vlocity_cmt, or vlocity_ps) to the native OmniStudio runtime that ships as part of the Salesforce platform in Industries Cloud licenses. It covers component inventory, namespace migration, use of the OmniStudio Migration Tool in Setup, LWC markup updates, Apex class updates, and a side-by-side testing strategy. NOT for new OmniStudio setup in greenfield orgs, nor for CPQ product migration, nor for re-platforming to non-Salesforce systems.

---

## Before Starting

Gather this context before working on anything in this domain:

- **Identify the Vlocity namespace.** Three Vlocity namespaces exist in active use: `vlocity_ins` (Insurance and Health Cloud), `vlocity_cmt` (Communications Cloud), and `vlocity_ps` (Public Sector Solutions). The namespace determines which managed package is installed and which service class names appear in Apex. The migration path is the same for all three, but the find-and-replace strings differ.
- **Confirm native OmniStudio entitlement and enablement.** Native OmniStudio requires the `enableOaForCore` org setting to be enabled. This setting is controlled by Salesforce support or via the OmniStudio Settings page in Setup (available once the Industries Cloud license includes OmniStudio). Enabling this setting does NOT automatically convert existing Vlocity components — conversion requires running the OmniStudio Migration Tool.
- **Understand the two-track deployment window.** During migration, both the Vlocity managed package and native OmniStudio can coexist in the org for a transitional period. This means components can be tested side-by-side before the managed package is uninstalled. However, mixed-namespace references in a single LWC file or Apex class will cause runtime failures.
- **Know the feature gap risk.** As of Spring '25, most OmniScript, DataRaptor, Integration Procedure, and FlexCard features have native equivalents. However, some Vlocity-specific features — particularly around OmniOut (external deployment of OmniScripts outside Salesforce), certain Vlocity Industry-specific DataPack types, and advanced CPQ integration hooks — may not have direct native counterparts. Inventory these before committing to a migration timeline.

---

## Core Concepts

### Two Deployment Models: Vlocity Managed Package vs Native OmniStudio

Salesforce Industries Cloud components (OmniScript, DataRaptor, Integration Procedure, FlexCard) have historically been delivered via Vlocity managed packages with industry-specific namespaces. These packages predate Salesforce's acquisition of Vlocity and are still installed in many production orgs.

Native OmniStudio, available since Winter '23 as GA, ships the same component set as part of the core Salesforce platform under the `omnistudio` namespace. No separate package is installed. Components are built and stored as platform metadata, not as managed package records.

The key distinction is where the component definitions live. In a Vlocity org, OmniScript definitions are stored as custom object records under `%vlocity_namespace%__OmniScript__c`. In a native org, they are stored as platform metadata with the `OmniScriptDefinition` metadata type. This difference drives the migration complexity — it is not just a namespace rename.

### The OmniStudio Migration Tool

Salesforce provides a Setup-based OmniStudio Migration Tool (also called the OmniStudio Migration Assistant) that automates the conversion of Vlocity managed package components to native OmniStudio format. The tool scans the org for installed Vlocity components, converts the component definitions from managed package records to native metadata, and registers them in the native OmniStudio runtime.

The Migration Tool handles OmniScripts, DataRaptors, Integration Procedures, and FlexCards. It does not handle custom LWC components that embed or extend these components, Apex classes that call Vlocity service classes, or DataPacks that include non-OmniStudio component types.

After running the Migration Tool, practitioners must separately:
1. Update all LWC markup that references managed package component tags.
2. Update all Apex code that calls `%vlocity_namespace%.IntegrationProcedureService` or similar.
3. Update any DataPacks or deployment scripts that reference Vlocity object API names.

### Namespace Differences in Code and Metadata

The namespace differences between Vlocity and native OmniStudio surface in four places:

1. **LWC HTML markup** — Managed package uses `<c-omni-script>`, native uses `<omnistudio-omni-script>`. Same pattern applies to FlexCard (`<c-flex-card>` vs `<omnistudio-flex-card>`) and other components.
2. **Apex class references** — Managed package calls go to `vlocity_ins.IntegrationProcedureService.runIntegrationService(...)`. Native calls go to `omnistudio.IntegrationProcedureService.runIntegrationService(...)`.
3. **SOQL queries** — Any Apex or Flow that queries Vlocity objects (e.g., `vlocity_ins__OmniScript__c`) must be updated to query native OmniStudio objects or removed if the component is now a metadata type rather than a record-stored definition.
4. **DataPack export/import tooling** — The Vlocity Build Tool (VBT) and its DataPacks format are not compatible with native OmniStudio. Native OmniStudio uses standard Salesforce deployment (SFDX/CLI, Metadata API). Projects that use DataPacks for CI/CD must rebuild their deployment pipelines.

### Side-by-Side Testing and Cutover Strategy

Because the managed package and native runtime can coexist during migration, the recommended approach is:
1. Run the Migration Tool to create native copies of all components.
2. Test the native copies in a sandbox while the Vlocity versions remain active.
3. Update all LWC and Apex references to point to native components.
4. Perform user acceptance testing on the native versions.
5. Set Vlocity components to inactive/deprecated.
6. Uninstall the managed package once all dependencies are resolved.

This approach reduces the cutover risk but requires careful management of component activation states — activating a native OmniScript with the same type/subtype as an active Vlocity OmniScript can cause conflicts depending on how components are invoked.

---

## Common Patterns

### Pattern 1: Bulk Namespace Audit Before Migration

**When to use:** Before running the Migration Tool, to understand the full scope of changes required in custom code.

**How it works:**
1. Run the checker script (`check_vlocity_to_native_omnistudio_migration.py --manifest-dir force-app/`) to scan all LWC HTML files for `c-omni-script`, `c-flex-card`, and similar managed package tags.
2. Scan all Apex class files for `vlocity_ins.`, `vlocity_cmt.`, or `vlocity_ps.` references.
3. Scan all custom metadata, workflow rules, and Process Builder flows for Vlocity object API names.
4. Produce a count of affected files and a mapping of Vlocity references to their native equivalents.
5. Use the count to scope migration effort and identify high-risk areas for testing.

**Why not the alternative:** Running the Migration Tool blind, without a prior audit, means practitioners discover broken LWC and Apex components only after the native runtime is active. Pre-auditing catches the custom code scope early.

### Pattern 2: Phased Component Cutover by Domain

**When to use:** Large orgs with hundreds of OmniScripts, DataRaptors, and Integration Procedures where a single-pass migration is high risk.

**How it works:**
1. Group components by business domain (e.g., Claims, Billing, Service).
2. Migrate one domain at a time: run the Migration Tool scoped to that domain's components, update LWC and Apex for that domain, test in sandbox, then promote.
3. Use Vlocity component active/inactive flags to control which version is live for end users during the transition.
4. Track progress in a migration tracker spreadsheet with component name, migration status, test result, and cutover date.

**Why not the alternative:** A single all-at-once cutover is high risk for large component inventories. If issues are discovered post-cutover, rolling back requires reinstating Vlocity component activation and reverting code — which is operationally complex and error-prone.

### Pattern 3: DataPack Pipeline Replacement

**When to use:** The org uses the Vlocity Build Tool (VBT) or a DataPacks-based CI/CD pipeline, which does not work for native OmniStudio components.

**How it works:**
1. Identify all DataPack export/import jobs in the CI/CD pipeline.
2. Replace DataPack exports with Salesforce CLI (`sf project retrieve`) using native OmniStudio metadata types (`OmniScriptDefinition`, `OmniIntegrationProcedure`, `OmniDataTransform`, `OmniUiCard`).
3. Update deployment scripts to use `sf project deploy` instead of the VBT deploy command.
4. Validate the new pipeline in a CI environment before decommissioning the VBT pipeline.

**Why not the alternative:** Attempting to continue using DataPacks for native OmniStudio components leads to silent data loss in deployments. Native OmniStudio components are platform metadata, not records, and DataPacks cannot serialize them correctly.

---

## Decision Guidance

| Situation | Recommended Approach | Reason |
|---|---|---|
| Org has fewer than 50 OmniScripts and DataRaptors | Single-pass Migration Tool run + bulk code update | Low complexity; manageable testing scope |
| Org has 100+ components across multiple domains | Phased domain-by-domain migration | Limits blast radius; allows domain-level testing |
| Custom LWC uses `c-omni-script` tag | Replace with `omnistudio-omni-script` after Migration Tool run | Native runtime does not resolve managed package component tags |
| Apex class calls `vlocity_ins.IntegrationProcedureService` | Replace with `omnistudio.IntegrationProcedureService` | Managed package service class is not available in native runtime |
| CI/CD pipeline uses Vlocity Build Tool DataPacks | Rebuild pipeline using SFDX + native metadata types | VBT cannot serialize native OmniStudio metadata |
| Vlocity OmniOut is in use (external OmniScript embedding) | Assess native OmniOut equivalent before migrating | Native OmniOut support is not fully equivalent to Vlocity OmniOut in all releases |
| Component uses a Vlocity-only DataPack type (e.g., Product Catalog) | Do not attempt to migrate via Migration Tool | Only OmniStudio-type components (OmniScript, DR, IP, FlexCard) are in scope |

---

## Recommended Workflow

Step-by-step instructions for an AI agent or practitioner working on this task:

1. **Run a namespace audit.** Execute `python3 scripts/check_vlocity_to_native_omnistudio_migration.py --manifest-dir force-app/` on the org's source metadata to identify all Vlocity namespace references in LWC, Apex, and metadata files. Record the count and file list.
2. **Inventory Vlocity components.** In the org Setup page, open the OmniStudio Migration Tool (Setup > OmniStudio > Migration Tool). Review the list of Vlocity OmniScript, DataRaptor, Integration Procedure, and FlexCard components discovered. Note any components flagged as not migrateable.
3. **Enable native OmniStudio if not already active.** Confirm `enableOaForCore` is set to `true` in the org's OmniStudio Settings. If not, coordinate with Salesforce support or your account team to enable it — this is a licensed feature, not a self-service toggle in all orgs.
4. **Run the OmniStudio Migration Tool.** In Setup, use the Migration Tool to migrate all eligible components. The tool creates native copies of the components. Migrated components are initially inactive. Review the migration log for any components that were skipped or flagged with errors.
5. **Update custom code.** Replace all Vlocity managed package references in LWC HTML files (component tags), Apex classes (service class calls and SOQL object names), and any custom metadata or configuration files. Use the namespace audit output from step 1 as the hit list.
6. **Activate native components and test side-by-side.** In a sandbox, activate the native copies of migrated components. Run functional tests against the native versions. Compare output against the still-active Vlocity versions. Resolve any behavioral differences — these commonly arise from DataRaptor formula differences, Integration Procedure HTTP action namespace changes, or FlexCard data source bindings.
7. **Promote and decommission Vlocity.** Once native components pass UAT, deactivate Vlocity components, deploy the updated LWC and Apex code, and validate in production. After a monitoring period, uninstall the Vlocity managed package to eliminate the managed package dependency.

---

## Review Checklist

Run through these before marking work in this area complete:

- [ ] All LWC HTML files use `omnistudio-*` component tags, not `c-omni-script` or `c-flex-card`
- [ ] All Apex classes reference `omnistudio.IntegrationProcedureService`, not `vlocity_ins/cmt/ps.IntegrationProcedureService`
- [ ] CI/CD pipeline uses SFDX + native metadata types, not Vlocity Build Tool DataPacks
- [ ] OmniStudio Migration Tool log reviewed; no components in error or skipped state without documented reason
- [ ] All native migrated components activated and functionally tested in sandbox
- [ ] DataRaptor formulas and Integration Procedure HTTP actions verified for namespace-specific differences post-migration
- [ ] Vlocity OmniOut usage assessed and native equivalent confirmed or gap documented
- [ ] Vlocity managed package uninstall dependency check completed (no remaining references)

---

## Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

1. **Migration Tool creates inactive copies — they are not live until manually activated** — After running the OmniStudio Migration Tool, all converted native components are created in an inactive state. Practitioners who assume the migration is complete immediately after the tool run will find that end users still hit the Vlocity versions. Each component must be explicitly activated in the OmniStudio designer, or via metadata deployment with the `isActive` flag set to `true`.
2. **Vlocity OmniScript type/subtype conflicts with native copies** — If both a Vlocity OmniScript and its native migrated copy share the same type and subtype, and both are active simultaneously, the runtime can resolve to either version depending on how the component is launched (FlexCard action, LWC tag, URL invocation). This creates unpredictable user experiences during the transition window. Deactivate the Vlocity version before activating the native version.
3. **DataRaptor formulas use namespace-prefixed field names that break post-migration** — Some DataRaptor Extract and Load operations that were built for Vlocity managed packages include field API names prefixed with the Vlocity namespace (e.g., `vlocity_ins__Status__c`). After migration, if the org's data model still has these fields on standard objects, the DataRaptor references remain valid. However, any DataRaptor that was referencing Vlocity-owned objects or fields that do not exist in the native model will fail silently — the Extract returns empty results rather than throwing an error.
4. **`sf project retrieve` does not retrieve native OmniStudio components by default** — Native OmniStudio metadata types (`OmniScriptDefinition`, `OmniIntegrationProcedure`, `OmniDataTransform`, `OmniUiCard`) must be explicitly listed in the `package.xml` manifest or project configuration for SFDX retrieval. Orgs that have migrated from Vlocity and assume their existing SFDX project captures all components will miss the native OmniStudio metadata in source control.
5. **Apex classes compiled against the Vlocity managed package fail after package uninstall** — Any Apex class in the org that references `vlocity_ins.*` (or the relevant namespace) will fail to compile if the managed package is uninstalled before the Apex is updated. This makes managed package uninstall a blocking step that can only happen after all Apex references are fully updated. Package uninstall can also be blocked if there are referencing metadata records, not just code.

---

## Output Artifacts

| Artifact | Description |
|---|---|
| Namespace audit report | Output of checker script listing all Vlocity namespace references by file and line |
| Migration Tool log | Log from the OmniStudio Migration Tool showing component conversion status |
| Updated LWC markup | HTML files with managed package tags replaced by native `omnistudio-*` tags |
| Updated Apex classes | Service class references updated from `vlocity_*` to `omnistudio` namespace |
| Rebuilt CI/CD pipeline | SFDX-based deployment pipeline replacing Vlocity Build Tool DataPacks |
| Side-by-side test plan | Test matrix comparing Vlocity and native component behavior for each migrated component |
| Post-migration validation checklist | Completed checklist confirming native runtime is fully operational and Vlocity dependencies cleared |

---

## Related Skills

- `omnistudio/omnistudio-lwc-integration` — use when updating LWC components to use native `omnistudio-*` tags post-migration; covers seed data, pubsub, and custom element conventions
- `omnistudio/omniscript-design-patterns` — use when native OmniScript behavior needs to be redesigned after migration uncovers feature gaps
- `omnistudio/dataraptor-patterns` — use when DataRaptor formulas or field references need rework post-migration
- `omnistudio/integration-procedures` — use when Integration Procedure HTTP actions or service class calls need namespace updates
- `omnistudio/omnistudio-deployment-datapacks` — use when understanding the Vlocity DataPacks model before replacing it with SFDX-native deployment