Transitioning to Salesforce OmniStudio Standard from OmniStudio for Vlocity

Introduction: In my previous blog post titled "Essential Preparations Before Transitioning to Salesforce OmniStudio Standard from OmniStudio for Vlocity", I've detailed the necessary steps to prepare for migrating to OmniStudio Standard from OmniStudio for Vlocity. Today, I'm excited to delve into the migration process itself, followed by the essential post-migration steps. Let's get started!

Let's Begin: Installing the OmniStudio Migration Tool in Your Migration Sandbox Org

Understanding the Tool: The OmniStudio Migration Tool is a Salesforce command-line interface (CLI) plug-in designed to facilitate the migration process seamlessly. Familiarize yourself with its functionality and significance in the migration journey.

Preparation Requirements: Before proceeding with the installation, ensure that your standard runtime sandbox org is authorized in Salesforce CLI. This step is crucial for seamless integration and execution of commands.

Compatibility and Availability: Check the compatibility and availability of the OmniStudio Migration Tool. It's compatible with Lightning Experience and is available in Enterprise, Performance, Unlimited, and Developer Editions. Ensure you have the required version, available in Winter '23 and later releases.

License Verification: Confirm that your org possesses both the OmniStudio license and the OmniStudio Standard features license, prerequisites for initiating the migration process. Contact your account executive if any licensing queries arise.

Reviewing Differences: Take the time to review and understand the disparities between OmniStudio and OmniStudio for Vlocity. This comprehension will provide valuable insights into the migration process and aid in strategizing effectively.

Deployment Recommendations: Familiarize yourself with our deployment recommendations to optimize your migration experience. These guidelines offer valuable tips and best practices for a successful transition.

Installing Salesforce CLI: If not already installed, follow the instructions to install Salesforce CLI. This tool is essential for executing commands and managing your Salesforce environment efficiently.

Authenticating Your Org: Open a Terminal window in Visual Studio Code and authenticate your standard runtime sandbox org in Salesforce CLI using the 'sf org login web' command. (See list of commands supported by Salesforce CLI here) Follow the prompts to securely authenticate your org credentials.

Installing the Migration Tool: With authentication complete, proceed to install the OmniStudio Migration Tool plug-in. Execute the below command in your Terminal window to initiate the installation process.

sf plugins install @salesforce/plugin-omnistudio-migration-tool        

Ready to Proceed: Congratulations! With the successful installation of the OmniStudio Migration Tool, you're now equipped to embark on your migration journey. Stay tuned for further guidance and support as we navigate through the migration process together.

Begin Your Migration: Executing the OmniStudio Migration Tool

Each time you initiate the OmniStudio migration tool, it seamlessly migrates all your active custom content, encompassing any previously migrated data.

Before running into the migration process, it's crucial to ensure that the OmniStudio Metadata setting is enabled.

In your command-line interface from your visual studio code, execute the following command:

//omnistudio migration command 
/* OPTIONS
  -n, --namespace=namespace                  //the namespace of the vertical package

  -a, --allversions        //commands to migrate all versions of FlexCards, OmniScripts, and Integration Procedures

  -u, --targetusername=targetusername        //username or alias for the target
                                             //org; overrides default target org

  -v, --targetdevhubusername=targetdevhubusername   //username or alias for the dev hub
                                                    //org; overrides default dev hub org

  --apiversion=apiversion              //override the api version used for
                                       //api requests made by this command

  --json                               //format output as json

  --loglevel=(trace|debug|info|warn|error|fatal|TRACE|DEBUG|INFO|WARN|ERROR|FATAL)  //logging level; default is warn 
*/

sf omnistudio:migration:migrate -u [email protected] --namespace=VLOCITY_PACKAGE_NAMESPACE --json

//example
sf omnistudio:migration:migrate -u [email protected] --namespace=vlocity_ins --json

//to migrate a specific component, add one of the following parameters
--only=dr
--only=ip
--only=os
--only=fc        

Replace [email protected] with your sandbox org username and VLOCITY_PACKAGE_NAMESPACE with the namespace of your sandbox org.

For instance:

sf omnistudio:migration:migrate -u [email protected] --namespace=vlocity_ins --json        

Once executed, the migration results will display in a new browser window for review.

To disable the custom runtime, execute the provided code using the Execute Anonymous tool in the Developer Console:

<packagename>.OmniStudioPostInstallClass.useStandardDataModel();        

Replace <packagename> with your package name namespace.

This code introduces two Omni Interaction Configuration settings that play crucial roles in facilitating a smooth transition. These settings primarily enable the OmniStudio managed package to seamlessly locate records within the OmniStudio standard data model. Additionally, they empower users to make modifications to standard objects directly within the OmniStudio designers. These designers are optimized to store content in the standard object data model and utilize the standard runtime for enhanced efficiency.

Validate the Migration: Verify the Transition in the Migration Sandbox Org

Upon deactivating the custom runtime in your standard runtime sandbox org, previously generated OmniScripts and FlexCards cease functionality. To ascertain the migration's success, assess the migrated content via the OmniStudio designers.

Upon completing satisfactory testing, proceed to deploy the migrated content to your User Acceptance Testing (UAT) sandbox org using the Metadata API. This UAT environment replicates your production environment, complete with the OmniStudio managed package incorporating pointers to custom objects.

Evaluate the migration in the User Acceptance Testing (UAT) Sandbox Org

Once you've thoroughly tested the migrated content in the migration sandbox org, proceed to push it to the User Acceptance Testing (UAT) sandbox org, which mirrors your production environment and includes an OmniStudio managed package with custom object references.

Before initiating the migration, ensure that the OmniStudio Metadata setting is enabled in the org.

1. The UAT sandbox org encompasses processes running in both custom and standard runtimes.
2. To authenticate Salesforce CLI in the UAT sandbox org, execute the command "sf org login web" and enter your org login credentials in the prompted browser tab.
3. Next, run the command "sf project retrieve start -m OmniScript,OmniDataTransform,OmniIntegrationProcedure,OmniUiCard" to retrieve the OmniStudio metadata, along with associated layouts, Lightning apps, and custom Lightning web components containing OmniStudio content.
4. Subsequently, execute the command "sf project deploy start -m OmniScript,OmniDataTransform,OmniIntegrationProcedure,OmniUiCard" to deploy the metadata to the UAT sandbox org.
5. Conduct thorough testing of your app to ensure the functionality of OmniStudio processes.
6. It's important to note that the OmniStudio designers in this org have access solely to the custom data model.

Revise References to Utilize the Salesforce Standard Data Model

Execute necessary cleanup procedures to guarantee the optimal functionality of your migrated content.

Change the sObject Data Model: Alter the Data Model from Custom to Standard Objects in the OmniStudio Designers and Managed Package Post-Migration.

1. Log in to the org where the data model change is intended.
2. Navigate to Setup and choose Developer Console.
3. Execute the following code:

// Switch Package to use Standard Objects OmniStudioPostInstallClass.useStandardDataModel();        

Update OmniStudio Customizations: After migration, it's crucial to update the syntax of custom functions in the metadata files for each migrated DataRaptor and Integration Procedure to ensure their proper functioning.

This task is particularly relevant for custom functions defined using the FunctionDefinition__mdt custom metadata in the managed package runtime in the INS 890.262 and later packages.

In the custom object model, functions are typically defined using this syntax:

FUNCTION(“ClassName”, “MethodName”, args)        

Whereas in the standard object model, the syntax is different:

FUNCTION(“CustomStringFunctions”, “functionName”, args)        

• Considerations for Migrating Custom Functions in Metadata to the FUNCTION('class','method',input) syntax

1. Custom Function Migration

Changed custom functions handling. Before migration, custom functions are defined in custom metadata as FunctionDefinition__mdt. After migration, custom functions use the same syntax: FUNCTION(“ClassName”, “MethodName”, args)

Before migration, the ClassName and MethodName are part of the custom metadata. For example, REPLACE(targetString, replacementString). After migration, change them to FUNCTION(“CustomStringFunctions”, “replace”, targetString, replacementString).

• Update Custom Lightning Web Components?After Migration

After migration, replace all vlocity references in the custom Lightning web component with omnistudio.?

In the JS file:

import { OmniscriptBaseMixin } from 'omnistudio/omniscriptBaseMixin’;

In the HTML file: <omnistudio-omniscript-formatted-rich-text class='slds-text-longform slds-path_guidance-content'

In the meta.XML file: <runtimeNamespace>omnistudio</runtimeNamespace>

• Update Custom Labels

Because the namespace has been modified, you must modify custom labels used in components. Do one of the following:

Add the omnistudio namespace, for example, omnistudio_<custom_label_name>

Recreate custom labels

• Considerations for Changing Apex References

Migrate Apex classes with VlocityOpenInterface to implements omnistudio.VlocityOpenInterface, callable

For more information see, Callable Implementations.

Open the metadata file for a migrated DataRaptor or Integration Procedure.

Search for a function, for example, REPLACE(targetString, replacementString).

Change the syntax, for example, FUNCTION(“CustomStringFunctions”, “replace”, targetString, replacementString).

Update References to DataRaptors from Apex After Migration: In the standard object data model, it's essential to note that DataRaptor names are restricted to alphanumeric characters only. When using the OmniStudio Migration Tool to transition references to DataRaptors in FlexCards, OmniScripts, and Integration Procedures, any special characters in the DataRaptor names will be automatically changed. However, if there are references to DataRaptors in other contexts, such as in Apex code, and their names include special characters, manual intervention is required to update the names accordingly.

To locate references to DataRaptors in Apex classes, search within .cls files retrieved through the Metadata API or Salesforce CLI. If you modify a reference to a DataRaptor in Apex, ensure to create a corresponding DataRaptor with the new name using the custom data model.

/* Specify DataRaptor extract or transform to call */
String DRName = 'DataRaptorName'; 
/* Populate the input JSON */
Map<String, Object> myTransformData = new Map<String, Object>{'MyKey'=>'MyValue'}; 
/* Call the DataRaptor */
vlocity_ins.DRProcessResult result = vlocity_ins.DRGlobal.process(myTransformData, DRName); 
/* Deserialize the DataRaptor output for processing in Apex */ 
List<Map<String, Object>> myTransformResult = (List<Map<String, Object>>)result.toJsonList();        

By ensuring that DataRaptor names adhere to the standard object data model's requirements and updating references accordingly, you maintain the integrity and functionality of your Apex code post-migration.

Update Integration Procedure Type and Subtype After Migration: Within the standard object data model, Integration Procedure types and subtypes are restricted to alphanumeric characters. While the OmniStudio Migration Tool typically handles the conversion of Integration Procedure references in FlexCards and OmniScripts, situations arise where manual intervention is needed. Specifically, if an Integration Procedure is referenced outside these contexts, like in Apex, or if its type or subtype name incorporates special characters, manual renaming of the affected type or subtype becomes necessary.

Update Remote Actions: To ensure seamless functionality of remote actions post-migration from OmniStudio for Vlocity to OmniStudio Standard, it's crucial to update any Apex classes utilized in remote actions with the appropriate syntax.

In the custom runtime environment, you would implement the VlocityOpenInterface class in any Apex class intended for remote actions.

However, in the standard runtime, the implementation shifts to the System.Callable class.

Replace all instances of VlocityOpenInterface with the following code snippet:

omnistudio.VlocityOpenInterface, Callable        

Furthermore, integrate the following code snippet into the class:

public Object call(String action, Map<String,Object> args)
{
    Map<String,Object> inputMap = (Map<String,Object>)args.get('input');
    Map<String,Object> outMap = (Map<String,Object>)args.get('output');
    Map<String,Object> options = (Map<String,Object>)args.get('options');

    return invokeMethod(action, inputMap, outMap, options);
}        

This adaptation ensures smooth transition and optimal performance of remote actions within the OmniStudio Standard environment.

Deploy the Migrated Objects to Production

Once you've thoroughly tested your migrated content in your sandbox orgs, it's time to deploy it to production. Here's how:

1. Authenticate Salesforce CLI in your production org by running the sf org login web command and entering your org login credentials in the new browser tab.
2. Retrieve the OmniStudio metadata along with layouts, Lightning apps, and custom Lightning web components that include OmniStudio content using the command sf project retrieve start -m OmniScript,OmniDataTransform,OmniIntegrationProcedure,OmniUiCard
3. Deploy the retrieved metadata to the production org with the command sf project deploy start -m OmniScript,OmniDataTransform,OmniIntegrationProcedure,OmniUiCard.
4. Test your app to ensure that your OmniStudio processes function as expected.
5. Replace any components that were using the custom object data model with migrated components that use the standard object data model. Locate migrated OmniScript components using the Type, Subtype, and Language fields, and FlexCard components using the Name field.
6. After migrating your content, remember to turn off custom runtime to complete the process.

Conclusion: In conclusion, transitioning to Salesforce OmniStudio Standard from OmniStudio for Vlocity marks a significant shift towards a more streamlined and efficient workflow. Throughout this journey, we've explored essential preparations, migration steps, and post-migration considerations. By embracing this transition, organizations can leverage the full potential of OmniStudio Standard, benefitting from its enhanced features and capabilities.

As we move forward, it's essential to continuously adapt and optimize our processes to meet evolving business needs. With careful planning, thorough testing, and ongoing refinement, the transition to OmniStudio Standard can pave the way for greater productivity, innovation, and success in the Salesforce ecosystem.

Together, let's embrace this transformative journey and unlock new possibilities with Salesforce OmniStudio Standard.

As always, In crafting this blog post, I drew inspiration from a variety of sources and referenced several insightful articles and resources. I extend my gratitude to https://developer.salesforce.com/ and https://help.salesforce.com/