Salesforce Docs Portal

Migrate Your Components in Your Development Sandbox (Vlocity Industries Managed Package and Standard Data Model)

Migrate Your Components in Your Development Sandbox (Vlocity Industries Managed Package and Standard Data Model)

Migrate all your custom components from Vlocity Industries managed package and standard data model to Omnistudio standard runtime using the Omnistudio Migration Assistant. It overwrites any previously migrated components.

Important
Important Run the Omnistudio Migration Assistant in Migrate mode only once. If you want to run the tool more than once, create a new development sandbox and run it.

Before You Begin

  • Run the Omnistudio Migration Assistant in Assess mode to make sure that you understand the impact. Skipping the Assess mode can lead to incomplete or incorrect migration.
  • Check the Migration Assessment Reports for Failed or Needs manual intervention status, and resolve them. See Review the Assessment Reports.
  • Make sure that no records in the Assessment Status column of the Assessment Report have a Failed or Needs manual intervention status before proceeding with the migration. See Review the Assessment Reports.
  • For Lightning web component (LWC) deployment, set the required environment variable in your org:
    1. Request an NPM repository access key from Salesforce Customer Support.
    2. Set the required environment variable in your org: 
      export OMA_AUTH_KEY=<your_auth_key>

      This environment variable provides the authentication key used to download the unmanaged component bundle from npm, bundle it, and deploy the components.

      Note
      Note If you're using Windows OS, add the OMA_AUTH_KEY in the environment variables.

To migrate all your custom components from Vlocity Industries managed package and standard data model to Omnistudio standard runtime:

  1. Make sure you completed Assess the Migration Readiness in Your Development Sandbox (Vlocity Industries Managed Package and Standard Data Model).
  2. Run the Omnistudio Migration Assistant tool in Migrate mode:

    sf omnistudio:migration:migrate [-u <string>] [-a] [--only=(dm|ip|os|fc|autonumber|cl)] [--relatedobjects=(apex|lwc|expsites|flexipage) [--verbose]

    • To migrate all versions of the components, use -a or –allversions:
      sf omnistudio:migration:migrate -u <YOUR_ORG_USERNAME@DOMAIN.COM> -a

      Where, YOUR_ORG_USERNAME@DOMAIN.COM is your username in the sandbox.

      Example: sf omnistudio:migration:migrate -u asmith@sample.com -a

      If you don’t specify either -a or –allversions parameter in the command, the Omnistudio Migration Assistant requests for your consent to migrate all versions of the Omnistudio components. Enter y to consent. If you don't consent to migrate all versions of the Omnistudio components, you cannot proceed with the migration.

    • To migrate specific components, use the -o or --only=dm parameter::
      • --only=dm: Data Mappers
      • --only=ip: Integration Procedures
      • --only=os: Omniscripts
      • --only=fc: Flexcards
      • --only=autonumber: Omni Global Auto Numbers
      • --only=cl: Custom Labels

      Example: sf omnistudio:migration:migrate -u asmith@sample.com –only=dm

      Note
      Note If you run Omnistudio Migration Assistant on a single component, instead of all components, the tool doesn’t switch to the standard data model.
    • To migrate specific or all related objects, use the -r or --relatedobjects parameter:
      • --relatedobjects=apex: Apex classes
      • --relatedobjects=lwc: Lightning web components
      • --relatedobjects=expsites: Experience Sites
      • --relatedobjects=flexipage: FlexiPages
      • --relatedobjects="apex,lwc,expsites,flexipage": all related objects

      Example: sf omnistudio:migration:migrate -u asmith@sample.com --relatedobjects=apex

    • To migrate username or alias for the target org and to override the default target org:
      • -u <target_username> or --targetusername=<target_username>: Username of the target org or alias you’ve set up in Salesforce CLI for that org.

      Example: sf omnistudio:migration:migrate -u asmith@sample.com

    • To control the amount of details shown in the command output, use the --verbose parameter with the command:

      Example: sf omnistudio:migration:migrate -u asmith@sample.com --verbose

  3. If multiple Omnistudio packages are found, select one of the packages by entering its number.
  4. Enter y to confirm that all records listed in the Assessment Status column in the Assessment Report are marked as either Ready for Migration or Warnings.
  5. Enter y to confirm that you accept changes to your custom code and the accompanying terms and conditions.
  6. When prompted, enter y or n to specify whether you already have a Salesforce project with related objects.
    • If you enter n:
      1. The tool connects to your org and retrieves related objects such as Apex classes, FlexiPages, Experience Cloud site pages, and Lightning web components (LWCs).
      2. Enter y to proceed.
      3. Create an empty project folder where the tool can retrieve and store related objects.
      4. When prompted, enter the path to the project folder. For example: /Users/<your_name>/Downloads/OMA
    • If you enter y:
      1. When prompted, enter the path to the project folder that contains the retrieved related objects. For example: /Users/<your_name>/Downloads/OMA
  7. Enter the target namespace (package name) for invoking the related objects in the Omnistudio managed package. For example: vlocity_ins, vlocity_ps, vlocity_cmt, and so on.
    Note
    Note

    Do not enter omnistudio as the target namespace.

  8. Enter y to confirm that you consent to enable the ExperienceBundle metadata API and migrate Experience Cloud sites.
  9. Enter y or n to specify whether you want the tool to deploy the related objects automatically.
    • If you enter y, the migration process starts and deploys the metadata changes for related objects such as Apex classes, Lightning web components (LWCs), Experience Cloud Site pages, and FlexiPages.
      Note
      Note If the required environment variable is not set in your org, LWCs are not deployed.
    • If you enter n, you must manually deploy the metadata changes for related objects.

    The migration process is initiated.

    After the migration completes, a confirmation message appears indicating that the reports are ready for review. For example: 

    Migration process for org <org_ID> is complete and reports are ready for review in the folder
        <local_folder_path>/migration_reports

    Where, <local_folder_path> represents the location on your machine where the migration reports are stored. The migration reports also appear in a new browser window.

    The migration reports are generated for these components:

    • Omniscripts
    • Flexcards
    • Data Mappers
    • Integration Procedures
    • Apex Classes
    • Omni Global Auto Numbers
    • FlexiPages
    • Experience Cloud Site Pages
    • Lightning Web Components
    • Custom Labels
  10. Click the component for which you want to view the migration report, and review the reports to make sure that all items listed are in Successfully migrated status. If there are any items that are marked as Skipped, review the items for any functional impacts. If there are items with the Failed status, contact Salesforce Customer Support. See Review the Migration Reports.

Post Migration Steps

After you review the reports, go to Omnistudio Settings:

  • Make sure that the Managed Package Runtime setting is turned off.
  • Make sure that the Omni Global Auto Number setting is turned on.
  • Manually turn off the Managed Package Designer setting.
  • Manually turn on the Deploy Custom Lightning Web Components in Standard Runtime setting.
Note
Note Depending on the number of Flexcards and Omniscripts, this deployment can take from a few minutes to an hour to complete. To monitor the deployment, go to Setup, find and select Deployment Status. If there are any deployment failures, turn off and turn on the setting, and monitor again.