Extend a Standard Lookup Component to Display Accounts and Cases

After completing this unit, you’ll be able to:

• Configure an OmniScript standard Lookup component.
  
• Extend the functionality of a standard OmniScript component with a custom Lightning web component.
  
• Describe the purpose of the code in the JS and XML files.
  
• Describe the purpose of the OmniScriptBaseMixin.
  

Account Selection

Now that Vijay has defined the structure of the Case Management OmniScript, he’s ready to configure the components one by one. First up is the standard Lookup component, which gives OmniScript users a way to select an account from a list of accounts. Hold on, there’s a twist to the story. Vijay wants to display the related cases for an account as soon as the OmniScript user selects the account. Can he pull it off?

Let’s look first at what Vijay configures in the Lookup to select an account and then move on to how he modifies the component’s behaviour.

OmniScript Lookup Component Basic Configuration

An OmniScript Lookup runs a query to get Salesforce data based on parameters you configure in the Lookup properties. The records return in Value/Label pairs and display in a dropdown list for an OmniScript user to select.

Let’s examine the Lookup properties.

Configure the Lookup: 

1. Enter SelectAccount for Name (1) and Select Account for Field Label (2).
   
2. Set Data Source Type (3) to SObject to get data from a Salesforce object.
   

Configure the Lookup Query:

1. For Lookup Order (1), enter 1 to set the priority if there are multiple queries.
   
2. For Lookup Object (2), select Account as the SObject to run the query against.
   
3. Select = for Filter Operator (3) to return an exact match.
   
4. In Filter Value (4), enter ‘Customer - Direct’ to return matches for this account type.
   
5. In JSON Path (5), enter Accounts to set the return path for the filtered value.
   
6. Click Save. The Lookup Query Configuration window is displayed.
   

Next, set the label for the dropdown list of a Lookup component to a JSON value returned by the query. When a user selects a label, the value populates in the JSON node of the Lookup.

1. Go to the Populate Lookup Element With Query Results section.
   
2. Set Accounts:Id as the JSON Path to use as the value in the lookup (1).
   
3. Set Accounts:Name as the JSON Path to use as the label in the lookup (2).
   

Lookup Component Configuration to Get Cases

Vijay previews his work so far on the OmniScript, and it’s looking good. He sees that accounts display in a dropdown list, and it’s possible to select an account. Next up, he wants to display the cases for a selected account. 

Vijay knows that the caseSelectableItemLWC custom Lightning web component contains the logic to get cases for the account. But this Lightning web component needs to be notified when the user selects an account. Setting up this kind of notification isn’t straightforward with a standard OmniScript component, because it’s hard to determine when the lookup completes. 

It’s time to create a Lightning web component called accountLookupLWC. Its purpose is to send a message to notify the component that gets and displays cases when the user selects an account. 

Custom Lightning Web Component for Account Lookup

When Vijay creates the accountLookupLWC Lightning web component, he uses the functionality of the Lookup component but makes a small change. He doesn’t need to rewrite the whole Lookup component. Instead, he just overwrites a single function, which keeps the code short and maintainable. 

First, he imports the OmniScript Lookup component and extends it to become a custom component with an export statement. Now the component has all the functionality of the OmniScript Lookup. Next, he modifies the standard functionality slightly with a selectOption method. This way, each time a user selects an account, it triggers the selectOption event handler. The handler uses a pubsub statement to notify the caseSelectableItemLWC that the user has selected a new account. 

Pubsubs are the default way to communicate from a FlexCard to an OmniScript. Pubsub is short for publish and subscribe and is the standard way to publish (send) messages between Lightning web components. Use pubsubs and events to communicate from one Lightning web component to another. 

You can use imports and extensions when you make small changes to functionality. Lightning web components can only extend one element at a time, but they can import many elements at once, such as actions or pubsubs.

Account Lookup JavaScript

Here’s an example of the accountLookupLWC JavaScript file that modifies the standard Lookup. 

accountLookupLWC.js

import { LightningElement } from 'lwc';
import pubsub from 'omnistudio/pubsub';
import { OmniscriptBaseMixin } from 'omnistudio/omniscriptBaseMixin';
import OmniscriptLookup from 'omnistudio/omniscriptLookup';
export default class accountLookupLWC extends OmniscriptBaseMixin(OmniscriptLookup) {
selectOption(event) {
let attr = event.target.getAttribute('data-option-index');
const inputIndex = parseInt(attr, 10);
this.setSelected(inputIndex).then(()=> {
pubsub.fire("newAccountSelected", 'data', {"AccountId": this.lookupValue});
});
this.hideOptions();
}
}

This table shows code highlights.

Let’s explore the OmniScriptBaseMixin a little further.

OmniScriptBaseMixin

Import and extend the OmniScriptBaseMixin when you build a custom Lightning web component for use inside an OmniScript. This helps keep the codebase simple, which saves build and maintenance time. The imported functions from the extended basemixin component eliminate the need to write new code. 

Think of the basemixin as a middle layer that helps the Lightning web component interact with the OmniScript. For example, when you need data from the JSON, the OmniscriptBaseMixin gives you methods to update an OmniScript’s data JSON and to pass parameters. Various functions are available, including validation functions, navigation functions, and next and previous actions. 

Account Lookup XML

Here’s an example of the AccountLookup JS-meta.xml file, followed by code highlights. This configuration file defines the metadata values for the Lightning web component.

AccountLookup.js-meta.xml

<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
<apiVersion>47.0</apiVersion>
<isExposed>true</isExposed>
<runtimeNamespace>omnistudio</runtimeNamespace>
<targets>
<target>lightning__AppPage</target>
<target>lightningCommunity__Page</target>
<target>lightningCommunity__Default</target>
</targets>
</LightningComponentBundle>

Please note that the runtimeNamespace should not be used if Lightning Web Security is enabled in the org.

• If LWS is enabled, setting runtimeNamespace in your components causes errors similar to "Cannot use runtime namespace 'somename' in module c-someComponentName". To determine if LWS is enabled in your org, see Enable Lightning Web Security in an Org.
  
• LWS now support cross-namespace usage/imports, but if you have a runtimeNamespace specified in your LWC, it will break. In order to successfully use cross-namespace components, you have to a) NOT use runtimeNamespace, and b) turn on LWS.
  

This table shows code highlights.

Reuse the XML file for each of the custom Lightning web components you create for the Case Management OmniScript.

Lightning Web Component Deployment

After you deploy the custom Lightning web component to your org, select it in the LWC Component Override field, which is in the Lookup properties. 

To set up custom components so they deploy and display correctly in the OmniScript in your org, consider these tools: 

• Salesforce DX
  
• IDX Workbench
  

You can use both tools to compare the source and target files. When you use IDX Workbench with Visual Studio Code, you can migrate OmniStudio components from one org to another.

The Account Lookup component is complete. Next, Vijay works on the cases related to the account. 

Resources

• Trailhead: OmniStudio Developer Tools