Adding Coveo for ServiceNow to the Virtual Agent

You can configure the ServiceNow Virtual Agent to ask the end user for a short description of their issue and return relevant matching items.

Add Coveo for Service Now to the Virtual Agent

  1. Once you have installed the Virtual Agent plugin, navigate to Collaboration > Virtual Agent > Designer.

  2. Ensure you’re in the Coveo application scope.

  3. In the Virtual Agent Designer, click the topic in which you want to integrate Coveo.

  4. In the Topic Properties, click Edit Topic Flow.

  5. Add a Text user input to the flowchart and name it short_description. The end user should use this input to enter a short description of their issue.

  6. Optionally, create a Text bot response to return an answer such as: OK, here are some resources that might help.

  7. Right after the bot response, add a Script Output.

    1. Under Script Output Type, select Multi-Part.

    2. Under Script Response Message, paste the following:

      (function execute() {
        var va = new CoveoVirtualAgent();
        va.init(Portal, VirtualAgent);
        return va.getFormattedResults(String(vaInputs.short_description));
      })()
      
    3. Click Save.

  8. In the Coveo Cloud Administration Console, to maximize the relevance of results returned by the Virtual Agent:

    1. Create an Automatic Relevance Tuning (ART) model.

    2. Associate your model with the desired query pipeline, and while doing so, check the Comply with Intelligent Term Detection (ITD) box.

  9. Optionally, customize your Coveo for ServiceNow Virtual Agent integration.

Configure Your Query Pipeline

Once you have added Coveo for ServiceNow to your Virtual Agent, you must link your this deployment to a query pipeline in your Coveo organization.

  1. In the Coveo Cloud Administration Console, in the Query Pipelines page:

    • If you want to use an existing pipeline, select it, and then in the Action bar, click More > Edit.

    • Create a new pipeline for the Virtual Agent to use.

  2. In the Add/Edit a Query Pipeline panel, create a condition enforcing a specific search hub (Search hub is) for the pipeline. The filter value to enter depends on your Virtual Agent configuration:

    • If you didn’t provide scope and component values in the init function, enter ServiceNow.

    • If you provided scope and component values, enter them in the following format: scope_component.

      For a Virtual Agent with a Portal scope and a VirtualAgent component, your condition value should be Portal_VirtualAgent. Your complete pipeline condition is therefore Search Hub is Portal_VirtualAgent.

    With such a condition, your pipeline will be used for all queries originating from the Virtual Agent.

    If your pipeline already has a condition, ensure to include this previous condition in your new one with an OR operator.

    Your pipeline has the following condition: Search Hub is Portal_MyWidget. You want to link the Virtual Agent to this pipeline, so your new condition is Search Hub is Portal_MyWidget OR Search Hub is Portal_VirtualAgent. With this condition, your pipeline will be used for all queries originating from either the specified widget or the Virtual Agent.

Workflow Example

As an end user engages with the Virtual Agent to solve an issue, the following may take place:

  1. The Virtual Agent asks the end user for a brief description of their issue.

  2. The end user enters a short text.

  3. Coveo receives the query and extracts the most important keywords out of it.

  4. The Virtual Agent returns OK, here are some resources that might help..

  5. Coveo returns search results that are relevant to the issue described by the end user and displays these results in the Virtual Agent discussion panel.

  6. The end user clicks the result that seems most relevant to their current issue.

Customization

By default, Coveo for ServiceNow returns simple results in the Virtual Agent. Only the title and an excerpt are displayed in the Virtual Agent discussion panel.

If you want to customize how the results appear, you can pass a CoveoVirtualAgentResultsRenderer instance with a custom template as an optional third argument when calling the init method on your CoveoVirtualAgent instance.

To set a custom template on a CoveoVirtualAgentResultsRenderer instance, use the setTemplate method.

The following script contains a custom result template at line 3. The resultRenderer function is then passed as a parameter for the Virtual Agent.

(function execute() {
  var resultRenderer = new CoveoVirtualAgentResultsRenderer();
  var template = '<div><a href="{{clickUri}}" onclick="{{logClickEvent}}"></a>{{raw.author}} - {{title}}</div>';
  resultRenderer.setTemplate(template);  
  var va = new CoveoVirtualAgent();
  va.init("CustomerServicePortal or ITPortal or HRPortal", "Virtual Agent", resultRenderer);
  return va.getFormattedResults(String(vaInputs.short_description));
})()

Reference

CoveoVirtualAgent (Object Type)

The CoveoVirtualAgent object can forward requests to the Coveo Cloud Search and Usage Analytics APIs using input from the ServiceNow Virtual Agent environment (see the short_description user input mentioned under Add Coveo for Service Now to the Virtual Agent).

init (Function)

The init function initializes the CoveoVirtualAgent, granting it the ability to execute search requests and log usage analytics events.

Parameters:

  1. scope (string, optional): The scope under which you want to categorize the function. This parameter work similarly to the Scope widget option.

  2. component (string, optional): The component under which you want to categorize the function. This parameter work similarly to the Component widget option.

  3. resultRenderer (function, optional): To customize how the search results appear in the Virtual Agent, this function passes a CoveoVirtualAgentResultsRenderer instance that uses your custom HTML result template. If you don’t provide this parameter, the default template is used.

getFormattedResults (Function)

The getFormattedResults executes a query, therefore calling getSearchResults, and returns a MultiPartOutMsg to be displayed in the Virtual Agent. The query results are also saved in the Virtual Agent (vaVars) for more use. For example, you could reuse the initial end user input in a script later in the conversation.

Parameters:

  1. userQuery (string): The basic query expression (q) to send to the Search API. Normally, this will be set to the text entered in the short_description user input (see Add Coveo for Service Now to the Virtual Agent).

  2. context (string): Additional context to add to the query. This information is useful for Coveo ML ART and usage analytics reporting purposes (see Understanding Custom Context).

getSearchResults (Function)

The getSearchResults function executes a query and sends a search event to Coveo Analytics, and then returns the results from the query.

Parameters:

  1. userQuery (string): The basic query expression (q) to send to the Search API. Normally, this will be set to the text entered in the short_description user input (see Add Coveo for Service Now to the Virtual Agent).

  2. context (string): Additional context to add to the query. This information is useful for Coveo ML ART and usage analytics reporting purposes (see Understanding Custom Context).

getRenderer (Function)

The getRenderer function returns the resultRenderer.

getVisitorId (Function)

The getVisitorId function returns the visitor id, which is the unique identifier of the tracked end user as stored in the Coveo cookie.

setVisitorId (Function)

The setVisitorId function saves the visitor ID for future use.

Parameters:

  1. visitorId (string): The visitor ID.

CoveoVirtualAgentResultsRenderer (Object Type)

The CoveoVirtualAgentResultsRenderer object type formats results from a Coveo search so that they can be displayed in the Virtual Agent. This behavior can be customized through the use of various methods (setTemplate, setNumberOfResults, etc.).

You can pass an instance of this object in the desired state as an optional third parameter when calling the init function of a CoveoVirtualAgent instance.

From an object-oriented perspective, CoveoVirtualAgentResultsRenderer can be seen as a class whose public interface is documented below.

setTemplate (Function)

The setTemplate function accepts a single parameter: the HTML result template to use when rendering the results.

Parameters:

  1. template (string): The template to use to display query results. This template may include Mustache syntax to display dynamic query result field values (e.g., {{raw.myfield}}).

    Ensure that your custom result template includes a result link, i.e., an a tag whose href attribute is set to {{clickUri}} and whose onclick attribute is set to {{logClickEvent}}. Executing the logClickEvent function is essential to gather the data that will be analyzed by Coveo Machine Learning.

setNoResultsTemplate (Function)

The setNoResultsTemplate function sets the HTML template to use when no results are returned.

Parameters:

  1. template (string): The template to use when a query produces no results.

setNumberOfResults (Function)

The setNumberOfResults function sets the maximum number of results to display in the Virtual Agent. If the query yields a number of results that’s greater than this number, the number of results displayed is limited to the specified numberOfResults.

Parameters:

  1. numberOfResults (integer): The maximum number of results to display for the query.

createResultsMsg (Function)

The createResultsMsg function creates a new MultiPartOutMsg containing the results to display in the Virtual Agent. This function is required when using a custom result renderer.

Parameters:

  1. results (object): The query results (see Query Response Properties). This information is passed by CoveoVirtualAgent.

  2. params (object): The context of the renderer, i.e., information on how the results were retrieved. This information is passed by CoveoVirtualAgent.

What’s Next?

Configure your Coveo Machine Learning models.

Recommended Articles