While Salesforce Industries’ (formerly Vlocity) OmniStudio comes with an extensive collection of OmniScript elements, there may be times when the out-of-the-box functionality just won’t fulfill your business requirements. For example, you may need to display your data in a particular way, have a more interactive UI, or take users backwards or forwards in a sequence based on complex business logic. The good news is that you can achieve all these goals (and more) with custom LWCs in your OmniScript. The OmniScript itself can be exported as an LWC, so this pairing makes sense!
If you don’t have experience of controlling a Lightning Web Component (LWC) from OmniScript, and OmniScript from an LWC, then you are in for a treat. In this guide, we will review the basics of using custom LWCs in OmniScript and then learn how to control the OmniScript and get and update its JSON. Sample code is also available for download.
Step 1: Creating the LWC
Creating an LWC for use in OmniScripts is pretty straightforward. Begin by creating a LWC in VS Code, just like you would create a regular LWC.
Now, instead of the LightningElement, you will need to extend the OmniScriptBaseMixin component to interact with the OmniScript; see screenshot below:
After that, there’s one more change you will need to make. Open your component’s XML configuration and set isExposed to true and runtimeNamespace to the actual namespace of the Vlocity package. In my case it was the “omnistudio” – see screenshot below.
This is it! You are now ready to add your custom business logic and control your OmniScript. You can also refer to the sample code I’ve created for this article.
And we are now ready to add our LWC to an OmniScript!
Step 2: Adding Custom LWC to the OmniScript
To add your custom LWC to an OmniScript, locate “Custom Lightning Web Component” under the “Inputs” section of the “Build” tab and drag it over to the step’s canvas.
You will then need to give it a name and select your LWC from the list of available components:
That is it. You now have your custom LWC added to the OmniScript and ready to implement your logic.
Let’s begin by sending some configuration info down to our component so it can be used in different scenarios.
Step 3: Setting Custom Properties
Just like you can accept the parameters in the Lightning App Builder, you can accept parameters in the OmniScript Designer as well. Simply add your property names and values in the “Custom Lightning Web Component Properties” section on the “Properties” tab.
On the LWC side you will need a regular LWC property:
In this example I’ve added my LWC to the same OmniScript twice, so it appears in two different steps. Depending on what step we’re in, the LWC shows a different screen. On the first step, sampleOSStep LWC asks the user to enter their first and last name and on the second step it displays retrieved values.
The first instance of our sampleOSStep test LWC is added to the first step of OmniScript and has “Step 1” value sent to its “stepName” property.
Please note that LWC notation is used when referring to property names so this is spelled as “step-name” in the Properties pane.
This causes our LWC to display its first “enterValues” screen, which asks the user for their first and last name:
The second instance of sampleOSStep is added to the second step of OmniScript and predictably, it has “Step 2” value sent to its “stepName” property.
That causes our LWC to display the read-only version of the screen that displays the info entered on the first screen:
Now we can deploy and configure our custom LWC in the OmniScript. Let’s explore the ways we can use our code to control and interact with it.
Step 4: Interacting with the OmniScript
Once your component is in the OmniScript, you can control pretty much anything from within your code.
To navigate forward and back simply call omniNextStep():
…and call omniPrevStep() to navigate one step back.
To retrieve the data from OmniScript JSON, use the omniJsonData property. The code below populates the local “data” attribute with the content of the “data” element from the OmniScript JSON:
To push the data back to the OmniScript data JSON, call the omniApplyCallResp() method. It passes a JSON object into the OmniScript’s data JSON.
The method looks for the element that matches the root data node in the object you send to the same node inside the OmniScript’s JSON and places the data there. So, if you make the following call sending our first and last name data.
This will cause our OmniScript’s JSON to look like this:
You can also simply persist your custom LWC data inside the OmniScript’s steps structure as if it was one of the out-of-the-box OmniScript controls:
This causes our OmniScript’s JSON to look like this:
Note: This method has an optional second argument called aggregateOverride. When set to false, which is the default value, it adds the data into the element with every call. When set to true, this causes the call to override the data in our custom LWC element.
Finally, you have an option of saving your data in another storage medium – OmniScript State. This keeps it out of the OmniScript JSON.
To store the data between steps without placing it in the OmniScript JSON call the omniSaveState() method:
This places the content of the data property you send into the slot inside the OmniScript state called “data”. To retrieve it simply call omniGetSaveState():
Summary
If you were following the steps in this quick introduction, you are no longer bound by the features available in the standard OmniScript elements. Now you can implement any kind of complex business logic and offer your business users more customized and interactive experiences.
So, does it mean that you should implement most of your logic in custom LWCs? Probably not as this pushes the logic into the code thus defeating the benefits of the declarative point-and-click Vlocity OmniScript Builder. Just like with the spices you use when you cook, you may get better results with fewer custom LWCs.
Finally, if you are stuck in your current implementation or just have a feeling that you are not getting the maximum benefits out of your OmniStudio investment, don’t hesitate to reach out. We’ve been through a lot of Vlocity projects over the last six years and have a ton of best practices and “gotchas” to spare. You will find some of these tips, best practices and design patterns are at https://maximumvlocity.com/.
Also, please email me directly at dk@ecmsolutions.ca if you would like to explore if we may be a fit to supplement your current project team or otherwise help make your implementation a success. If you have not downloaded the sample code yet, you can get it from here.