How to create your own Custom Control

[Mark Roethof]

Hi all,

Wondering if anyone has been successful with building their own Custom Control for Virtual Agent and willing to share the how to.

So far I have seen no examples of building a Custom Control, and the Docs pages are incomplete. I have tried in the past though without luck.

Please don't reply on this post with a link to the Docs pages (as mentioned: are incomplete) or if you don't have any practical knowledge on this subject at all.

[Rasul Safa]

Hi Mark,

I don't know if you're still interested in this, but I recently implemented a custom control input in the virtual agent. The existing documentation for custom form controls glosses over the whole creating the UI component aspect of the form control. Basically, you need to create a custom Next Experience UI component to link to the created custom form control definition. To do that, you need to setup a local environment with Node, NPM and the ServiceNow CLI. Then you install the ui-component extension, setup your profile to connect to your remote instance, and create the local project. The guide I linked goes in-depth on how to do this. Now you can run the ui-component deploy command to send the packaged local component to ServiceNow, which you can then link to the custom form control. In the custom form control topic you also need to link up the inputs/outputs/handlers. The most important thing about the Virtual Agent UI components is managing the properties received. Here's an outline how a VA UI component is structured, taking advantage of the VA properties (controlData, responseValue, forceCloseControl) and the VA_CONTROL#VALUE_SENT event. A lot of the boilerplate is made by the "snc ui-component project [...]" command.

import {createCustomElement} from '@servicenow/ui-core';
import snabbdom from '@servicenow/ui-renderer-snabbdom';
import styles from './styles.scss';
const view = (state, {dispatch, updateState}) => {
    const {properties} = state;
    const data = properties.controlData.value;
    if(properties.forceCloseControl && !state.controlClosed) {
        updateState({controlClosed: true});
    }
    if(properties.responseValue) {
        return (<div>{properties.responseValue.action}</div>)
    }
    return (
        <div>
            {Object.keys(data).map((data, index) => {
                return (
                    <div className="record">
                        <h3>...</h3>
                        <p>.....</p>
                        {!state.controlClosed && <button type="button" on-click={() => updateState({abc: xyz})}>
                            <span>View Details</span>
                        </button>}
                    </div>
                );
            })}
            <br/>
            {state.abc && !state.controlClosed && <div>
                {Object.keys(...).map((id) => {
                    if (xyz === state.xyz) {
                        return (
                            <div>
                                <button type="button" on-click={() => {
                                   dispatch('VA_CONTROL#VALUE_SENT', {
                                      value: { action: id }
                                    });
                                    updateState({controlClosed: true});
                                }}>Click Me To Send Data to VA</button>
                            </div>
                        );
                    }
                })}
            </div>}
        </div>
    );
}
createCustomElement('component-name', {
    renderer: {type: snabbdom},
    view,
    styles,
    properties: {
        controlData: {default: ""},
        responseValue: {default: null},
        forceCloseControl: {default: false}
    },
    setInitialState({host, properties}) {
        return { abc: defgh, controlClosed: false };
    }
});