Create a custom Insight Panel

This is for:

Developer System Administrator

Coveo offers a Hosted Insight Panel solution that delivers a seamless, low-code experience out of the box. It lets you display contextual recommendations and results related to a Salesforce record (such as Cases), helping agents quickly access relevant content. It draws on Coveo Machine Learning to improve efficiency and resolution quality.

However, there are situations where development teams require more flexibility or integration capabilities than what the Hosted Insight Panel configuration options can provide. For example, you might need full control over the rendering logic, or to make deep user interface customizations, or to carry out more advanced record-driven interactions.

In such scenarios, consider building a custom Insight Panel using Quantic components. This article explains how to implement such custom, non-hosted Insight Panels using Coveo Quantic. It uses the ExampleInsightPanel component from the solutionExamples folder in the Quantic project repository. We recommend using this example as a starting point for your own implementation.

Prerequisites

Create a new Lightning Web Component

Create your LWC (for example, exampleInsightPanel) using the lightning generate component command:

sf lightning generate component --name exampleInsightPanel --type lwc

Your new LWC should have the following structure:

exampleInsightPanel/
├── exampleInsightPanel.html
├── exampleInsightPanel.js
├── exampleInsightPanel.js-meta.xml

HTML

The HTML file is where you assemble Quantic Insight Panel components to create your custom Insight Panel. These components are designed to offer flexibility for developers needing to tailor the agent experience beyond what the Hosted Insight Panel provides.

The following sample is abbreviated for clarity in this documentation article. For the full sample, see exampleInsightPanel.html in the Quantic project repository.

<template>
  <div onquantic__registerresulttemplates={handleResultTemplateRegistration}> 1
    <c-quantic-insight-interface engine-id={engineId} insight-id={insightId}> 2
      <c-quantic-aria-live></c-quantic-aria-live>
      <div 3
        class="insight-panel_layout slds-box slds-is-relative slds-grid_align-center"
      >
        <div class="insight-panel_header slds-var-p-bottom_x-small">
          <div class="slds-grid">
            <div class="insight-panel_search-box">
              <c-quantic-search-box
                without-submit-button
                engine-id={engineId}
              ></c-quantic-search-box>
            </div>

            <!--- ... --->
            </div>
          </div>
        </div>

        <c-quantic-facet-manager engine-id={engineId}>
          <c-quantic-facet
            field="objecttype"
            label="Type"
            engine-id={engineId}
            data-cy="type"
          ></c-quantic-facet>
          <!--- ... --->
        </c-quantic-facet-manager>

        <div class="insight-panel_tabs">
          <c-quantic-tab-bar>
            <c-quantic-tab
              name="All"
              label="All"
              engine-id={engineId}
              is-active
            ></c-quantic-tab>
            <!--- ... --->
          </c-quantic-tab-bar>
        </div>

        <!--- ... --->
      </div>
    </c-quantic-insight-interface>
  </div>
</template>
1 Attach the handleResultTemplateRegistration function on the onquantic__registerresulttemplates event thrown to register result templates (more details below).
2 Use the QuanticInsightInterface component and set its engine-id and insight-id properties. This component is required to handle the Headless insight engine and localization configurations. Most Quantic components require an engine-id, and all components that belong to a given interface must have the same engine-id. Sharing this engine-id across components is what allows the QuanticInsightInterface component to establish the connection between them. You must have one and only one QuanticInsightInterface component per engine-id in a given page or Digital Experience.

The insight-id property connects the component to a specific Insight Panel configuration. You’ll define the engineId and insightId variables in your JavaScript file.
3 Out of the box, Quantic lets you use Salesforce Lightning Design System (SLDS) styling classes. This example uses the Grid utility.

XML

The XML configuration file is where you define the targets of your LWC. You also specify the parameters whose values are requested through the Salesforce Experience Builder and can set their default values. These values take precedence over the values you set in your LWC JavaScript file.

<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <apiVersion>56.0</apiVersion>
    <isExposed>true</isExposed>
    <targets> 1
        <target>lightning__RecordPage</target>
        <target>lightning__AppPage</target>
        <target>lightning__HomePage</target>
        <target>lightningCommunity__Page</target>
        <target>lightningCommunity__Default</target>
    </targets>
    <targetConfigs>
        <targetConfig targets="lightningCommunity__Default, lightning__AppPage, lightning__RecordPage, lightning__HomePage"> 2
            <property name="engineId" type="String" default="example-insight-panel" label="Enter Coveo Headless engine ID"/>
            <property name="insightId" type="String" default="" label="The insight panel config ID"/>
        </targetConfig>
    </targetConfigs>
</LightningComponentBundle>
1 Specifies the targets in which your LWC is available.
2 Expose the properties that you want to be able to edit in the Salesforce Experience Builder. You can set different values for each target. You pass these variables to instantiate Quantic components in your HTML file.

JavaScript

This is where you connect your result templates with your main HTML file using conditions. It’s also where you define the variables that you use in the HTML file and set their values in the XML file.

The following sample is abbreviated for clarity in this documentation article. For the full sample, see exampleInsightPanel.js in the Quantic project repository.

// @ts-ignore
import {
  getHeadlessEnginePromise,
} from 'c/quanticHeadlessLoader';
// ...

export default class ExampleInsightPanel extends LightningElement {
  /** @type {string} */
  @api engineId = 'example-insight-panel'; 1
  /** @type {string} */
  @api insightId = '142be676-703c-445f-b2d3-fcc7c0a3ded8'; 2

  connectedCallback() { 3
    this.template.addEventListener(
      'quantic__insightinterfaceinitialized',
      this.handleInterfaceLoad
    );
  }
  disconnectedCallback() { 4
    this.template.removeEventListener(
      'quantic__insightinterfaceinitialized',
      this.handleInterfaceLoad
    );
  }

  handleInterfaceLoad = (event) => {
    event.stopPropagation();
    getHeadlessEnginePromise(this.engineId).then((engine) => {
      engine.executeFirstSearch();
    });
  };
}
1 Define the variables that you use in the HTML file and set their default values. Here, you define a unique identifier for your Headless engine.
2 This variable stores your Insight Panel configuration ID.
3 The connectedCallback lifecycle hook is called when the component is inserted into the DOM. Use it to listen to the quantic__insightinterfaceinitialized event, emitted by the QuanticInsightInterface component when it has finished loading. When this event is caught, call the handleInterfaceLoad function to execute the first search, ensuring results are displayed.
4 The disconnectedCallback lifecycle hook is called when the component is removed from the DOM. Use it to remove the event listener that you attached in the connectedCallback lifecycle hook.

CSS

Use SLDS styling classes in your LWC markup. Add a .css file to the root of your project folder for additional styling.

.insight-panel_layout {
  background-color: var(--lwc-colorBackgroundAlt, rgb(255, 255, 255));
  border-radius: var(--lwc-borderRadiusMedium, 0.25rem);
  overflow: hidden;
  width: 100%;
  max-width: 500px;
  margin: auto;
  -webkit-box-shadow: 0 2px 2px 0 rgb(0 0 0 / 10%);
  box-shadow: 0 2px 2px 0 rgb(0 0 0 / 10%);
}

.insight-panel_search-box {
  flex: 1;
}

c-quantic-facet-manager,
c-quantic-results-per-page {
  display: none;
}

.insight-panel_body {
  min-height: 25rem;
}

Platform token provider

If you were to deploy your LWC now, it would return results.

Quantic custom Insight Panel with sample results

However, these results come from a sample organization which is only meant for testing. For a real implementation, you need to configure platform token authentication in your Insight Panel. This means that each user gets their own platform token, with appropriate privileges to access your organization’s content. Personalized platform tokens also let you use personalized usage analytics and machine learning features.

If you’ve installed and configured Coveo for Salesforce v4 or a later package in your Salesforce organization, it’s typically enough to copy the InsightTokenProvider Apex class, along with its meta.xml file, into your Salesforce DX project. This class can automatically fetch your Salesforce users' information to generate platform tokens for them. This is the best option for most use cases.

If you haven’t installed Coveo for Salesforce v4 or a later package, or if the InsightTokenProvider Apex class doesn’t fit your needs, you’ll have to implement your own platform token provider, building on the InsightTokenProvider example.

Once you’ve copied or created your platform token provider Apex class, you need to modify the Headless configuration in your Quantic installation so that it calls your Apex class. You can find the InsightController file at force-app/main/default/classes. Locate the following line:

return SampleTokenProvider.getHeadlessConfiguration();

and modify it so that it leverages your platform token provider instead:

return YOUR_TOKEN_PROVIDER.getHeadlessConfiguration();

where you replace YOUR_TOKEN_PROVIDER with the name of your platform token provider Apex class, such as InsightTokenProvider if you copied it from the Quantic project.

If you’ve retrieved the Quantic project, you can make this change locally. After you deploy your project, your changes will be effective in your Salesforce organization. If you haven’t retrieved Quantic locally, you can navigate to the InsightController file from the Salesforce Developer Console and modify it there.

What’s next?