Add the application to the Virtual Agent

This is for:

Developer System Administrator

If you implemented the Virtual Agent in your ServiceNow instance, you can integrate Coveo for ServiceNow in the Virtual Agent to return relevant matching items.

Workflow example

As an end user engages with the Virtual Agent to solve an issue, the following takes 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.

  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 the results in the Virtual Agent discussion panel.

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

Integrate Coveo for ServiceNow in the Virtual Agent

  1. If you haven’t done so yet, activate the Virtual Agent plugin in your ServiceNow instance.

  2. Use the application picker, or the application list menu on the ServiceNow banner frame, to switch the application scope to the Coveo application, which is listed as AI-Powered Search & Recommendations by Coveo.

  3. Create a new Virtual Agent topic in which to integrate Coveo, or duplicate an existing topic to use as a base.

    Note

    You must create or duplicate the Virtual Agent topic in the AI-Powered Search & Recommendations by Coveo application scope.

  4. Navigate to Collaboration > Virtual Agent > Designer.

  5. In the Virtual Agent Designer, click the topic that you created or duplicated for use with Coveo.

  6. Click the Flow tab.

  7. Add a Text User Input component to the topic flow. This component lets a user enter a short description of their issue.

  8. Specify the following Text User Input component properties:

    1. Under User Input Properties, for the Name field, enter short_description.

    2. In the Prompt field, enter the text that you want to display as the initial prompt to the user, such as How can I help you?.

  9. Optionally, add a Text Bot Response component to the topic flow below the User Input component. This text appears after a user enters an issue description and is used to introduce the results returned by Coveo.

  10. Specify the following Text Bot Response component properties:

    1. Under Response Properties, enter a Name such as bot_response.

    2. Enter a Response Message such as OK, here are some resources that might help..

  11. Add a Script Output Bot Response component to the topic flow either below the Text Bot Response if you added one, or below the Text User Input. This component initializes Coveo search in your Virtual Agent topic.

  12. Specify the following Script Output Bot Response component properties:

    1. Under Response Properties, enter a Name such as coveo_output.

    2. In the Script Output Type list, select Multi-Part.

    3. Under Script Response Message, paste the following:

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

  13. Click Save.

    The following image shows the component flow of a simplified Virtual Agent topic:

    Virtual Agent flow

  14. Optionally, you can customize your integration. For example, you can specify a scope and component naming convention, which is useful when configuring query pipelines and query filters and associating them with your integration, or you can customize how search results appear in your Virtual Agent.

  15. Configure your query pipeline.

  16. To maximize the relevance of search results returned by Coveo in your Virtual Agent, in the Coveo Administration Console:

    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.

Configure your query pipeline

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

  1. In the Coveo Administration Console, on the Query Pipelines (platform-ca | platform-eu | platform-au) page:

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

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

  2. In the Add/Edit a Query Pipeline (platform-ca | platform-eu | platform-au) panel, create a condition enforcing a specific search hub (Search hub is) for the pipeline that points to your Virtual Agent. 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 the existing condition in your new one with an OR operator.

    Example

    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.

    The filter value to enter for the condition 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.

      Example

      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.

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 function method on your CoveoVirtualAgent instance.

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

Example

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));
})()

To customize your Virtual Agent integration

  1. Access the Script Output bot-response component of the Virtual Agent topic in which you integrated Coveo.

  2. Modify the Script Response Message as required. Refer to the Reference section for the list of objects and functions.

Reference

CoveoVirtualAgent (object type)

The CoveoVirtualAgent object can forward requests to the Coveo Search and Usage Analytics APIs using input from the ServiceNow Virtual Agent environment (see the short_description user input mentioned under Integrate Coveo for ServiceNow in 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 for more use (see Virtual Agent Scripts). 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 Integrate Coveo for ServiceNow In 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 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 Integrate Coveo for ServiceNow In 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 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.

Parameter:

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.

Parameter:

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

Important: Ensure that your custom result template includes a result link, that is, 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.

Parameter:

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.

Parameter:

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, that is, information on how the results were retrieved. This information is passed by CoveoVirtualAgent.

What’s next?

Configure query filters to ensure that the Coveo for ServiceNow components you configured in your public-facing and internal portals only return items from appropriate subsets of your Coveo organization's indexed content.