How to Place a Custom LWC in an Omniscript Block?

I have created a custom Lightning Web Component (LWC) and I want to use it inside an Omniscript. However, I am unable to place this custom LWC under a Block element in the Omniscript. What could be the reason for this, and how can I make it work properly?

Answer:
In Omniscript, placing a custom LWC inside a Block element requires some specific steps because Omniscript only recognizes components that extend its base functionality. Simply creating a standard LWC is not sufficient. To make a custom LWC compatible with Omniscript, you need to use the OmniscriptBaseMixin provided by Vlocity (Salesforce Industries). This mixin ensures that your component can interact with the Omniscript runtime, access data, and handle inputs/outputs correctly.

Here’s an example of how your LWC JavaScript file should be structured:

import { LightningElement } from 'lwc';
import { OmniscriptBaseMixin } from 'vlocity/omniscriptBaseMixin';

export default class YourCustomLwc extends OmniscriptBaseMixin(LightningElement) {
    // Your component logic here
}

import { LightningElement } from 'lwc';
import { OmniscriptBaseMixin } from 'vlocity/omniscriptBaseMixin';

export default class YourCustomLwc extends OmniscriptBaseMixin(LightningElement) {
    // Your component logic here
}

In this code, OmniscriptBaseMixin wraps your standard LightningElement, enabling it to function within Omniscript. Without this mixin, Omniscript will not recognize the component as valid to place inside Blocks or other containers.

Additionally, you must ensure your component’s metadata XML file is properly configured to be exposed and available to Omniscript:

<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <apiVersion>59.0</apiVersion>
    <isExposed>true</isExposed>
    <targets>
        <target>lightning__OmniscriptCustomBlock</target>
    </targets>
    <runtimeNamespace>c</runtimeNamespace>
</LightningComponentBundle>

<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <apiVersion>59.0</apiVersion>
    <isExposed>true</isExposed>
    <targets>
        <target>lightning__OmniscriptCustomBlock</target>
    </targets>
    <runtimeNamespace>c</runtimeNamespace>
</LightningComponentBundle>

Key points in the XML:

1. <isExposed>true</isExposed> makes the component available for use outside its folder, so Omniscript can recognize it.
2. <runtimeNamespace> specifies the namespace if you are using a managed package or simply c for a default unmanaged org.
3. <targets> must include lightning__OmniscriptCustomBlock so the Omniscript designer allows it under a Block element.

Once these steps are correctly implemented, your custom LWC should appear in the Omniscript Build tab when you search for “Custom Lightning Web Component” and allow you to drag it into a Block element without any issues.

This approach ensures that the LWC is fully compatible with Omniscript, maintains proper lifecycle hooks, and can handle data passed through Omniscript JSON inputs and outputs.

In Omniscript, Blocks are container elements that can hold multiple types of child elements, including standard fields, actions, and components. However, when it comes to custom Lightning Web Components, Omniscript does not automatically recognize them unless they are built to integrate with its runtime. This is why you can create an LWC normally, but it may not appear under a Block element. The Omniscript designer is looking for components that extend its base functionality using the OmniscriptBaseMixin.

Why OmniscriptBaseMixin is Required

The OmniscriptBaseMixin is a specialized mixin provided by Vlocity (Salesforce Industries) that allows an LWC to:

1. Access the Omniscript JSON data structure.
2. Read and write input/output variables in the Omniscript.
3. Respond to Omniscript events like navigation, validation, and save.
4. Maintain proper lifecycle hooks so that the Omniscript engine can manage the component.

Without this mixin, Omniscript treats your LWC as a standard Lightning component, which cannot participate in the Omniscript data or event flow, and therefore the designer prevents you from placing it in a Block.

Correct LWC JS Structure

Here’s the JavaScript for a basic Omniscript-compatible LWC:

import { LightningElement } from 'lwc';
import { OmniscriptBaseMixin } from 'vlocity/omniscriptBaseMixin';

export default class YourCustomLwc extends OmniscriptBaseMixin(LightningElement) {
    connectedCallback() {
        // Called when the component is inserted into the DOM
        console.log('Omniscript-compatible LWC loaded.');
    }

    handleAction() {
        // Example: updating a JSON variable in Omniscript
        this.omniUpdateDataJson({ fieldName: 'sampleField', value: 'newValue' });
    }
}

import { LightningElement } from 'lwc';
import { OmniscriptBaseMixin } from 'vlocity/omniscriptBaseMixin';

export default class YourCustomLwc extends OmniscriptBaseMixin(LightningElement) {
    connectedCallback() {
        // Called when the component is inserted into the DOM
        console.log('Omniscript-compatible LWC loaded.');
    }

    handleAction() {
        // Example: updating a JSON variable in Omniscript
        this.omniUpdateDataJson({ fieldName: 'sampleField', value: 'newValue' });
    }
}

Explanation:

• OmniscriptBaseMixin(LightningElement) wraps your LWC, giving it access to Omniscript methods like omniUpdateDataJson and omniApplyCallResp.
• Methods like connectedCallback() still work normally, but now the component can also interact with Omniscript events.
• Any data updates performed using Omniscript methods automatically flow back to the Omniscript runtime JSON, making the component fully interactive within Blocks.

Correct LWC Metadata Configuration

The XML file (component bundle metadata) is also crucial. A minimal example:

<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <apiVersion>59.0</apiVersion>
    <isExposed>true</isExposed>
    <targets>
        <target>lightning__OmniscriptCustomBlock</target>
    </targets>
    <runtimeNamespace>c</runtimeNamespace>
</LightningComponentBundle>

<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <apiVersion>59.0</apiVersion>
    <isExposed>true</isExposed>
    <targets>
        <target>lightning__OmniscriptCustomBlock</target>
    </targets>
    <runtimeNamespace>c</runtimeNamespace>
</LightningComponentBundle>

Key points explained:

1. <isExposed>true</isExposed>: Makes the component available in the App Builder and Omniscript designer.
2. <targets>: lightning__OmniscriptCustomBlock is essential—it tells Omniscript this component is allowed inside a Block. Without it, the designer won’t even display the component.
3. <runtimeNamespace>: If you are in an unmanaged org, c is fine. In a managed package, this should match your package namespace. This ensures Omniscript can properly reference the component at runtime.

How to Add the Component to Omniscript

Once your LWC is properly set up:

1. Go to Omniscript Builder → Build Tab.
2. Search for Custom Lightning Web Component.
3. You should now see your LWC listed.
4. Drag it inside the Block element.
5. Configure its inputs/outputs using the Omniscript designer, just like you would with standard elements.

Common Pitfalls

• Forgetting to use OmniscriptBaseMixin. The LWC will show up in the designer but won’t interact with Omniscript data correctly.
• Not specifying the target lightning__OmniscriptCustomBlock. The designer won’t allow the component inside a Block.
• Incorrect namespace in XML. Omniscript may fail at runtime if it cannot locate the component.
• Using LWC without Omniscript lifecycle methods, causing data changes to not reflect in Omniscript JSON.

Real-Time Project-Based Salesforce Course to Kick Start Your Career

Our Salesforce Course is designed to provide you with a deep understanding of the Salesforce platform, equipping you with the essential skills to succeed in the CRM field. The program covers important modules such as Salesforce Admin, Developer, and AI, blending theory with hands-on practice. You’ll gain practical experience through real-world projects and assignments, enabling you to solve complex business challenges using Salesforce solutions. Our expert instructors ensure that you gain both technical proficiency and relevant industry knowledge to thrive within the Salesforce ecosystem.

Beyond technical skills, our Salesforce training in Mumbai offers personalized mentorship, exam preparation, and interview coaching to enhance your career prospects. You’ll have access to comprehensive study materials, live project experience, and dedicated support throughout your learning journey. Upon completing the course, you’ll be fully prepared for certification exams and equipped with the problem-solving skills that employers seek. Start your Salesforce journey with us and unlock a world of career opportunities. Enroll for a Free Demo now!