---
title: Add the application to the Virtual Agent
slug: '3137'
canonical_url: https://docs.coveo.com/en/3137/
collection: coveo-for-servicenow
source_format: adoc
---
# Add the application to the Virtual Agent
If you implemented the [Virtual Agent](https://www.servicenow.com/docs/bundle/zurich-conversational-interfaces/page/administer/virtual-agent/concept/virtual-agent-landing-page.html) 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:

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

. The end user enters a short text.

. Coveo receives the query and extracts the most important keywords.

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

. 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.

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

## Integrate Coveo for ServiceNow in the Virtual Agent

. If you haven't done so yet, [activate the Virtual Agent plugin](https://www.servicenow.com/docs/bundle/zurich-conversational-interfaces/page/administer/virtual-agent/task/activate-virtual-agent.html) in your ServiceNow instance.

. Use the [application picker](https://www.servicenow.com/docs/bundle/zurich-application-development/page/build/applications/concept/c_ApplicationPicker.html), 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**.

. [Create a new Virtual Agent topic](https://www.servicenow.com/docs/bundle/zurich-conversational-interfaces/page/administer/virtual-agent/task/create-virtual-agent-topic.html) in which to integrate Coveo, or [duplicate an existing topic](https://www.servicenow.com/docs/bundle/zurich-conversational-interfaces/page/administer/virtual-agent/task/duplicate-virtual-agent-topic.html) 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.

. Navigate to **Collaboration** > **Virtual Agent** > **Designer**.

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

. Click the **Flow** tab.

. Add a **Text** User Input component to the [topic flow](#flow).
This component lets a user enter a short description of their issue.

. Specify the following **Text** User Input component properties:

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

.. 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?`.

. 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.

. Specify the following **Text** Bot Response component properties:

.. Under **Response Properties**, enter a **Name** such as `bot_response`.

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

. [[scriptoutput]]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.

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

.. Under **Response Properties**, enter a **Name** such as `coveo_output`.

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

.. Under **Script Response Message**, paste the following:

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

. Click **Save**.

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

![Virtual Agent flow | Coveo for ServiceNow](https://docs.coveo.com/en/assets/images/coveo-for-servicenow/virtual-agent-flow.png)

. Optionally, you can [customize](https://docs.coveo.com/en/3137#customization) your integration.
For example, you can specify a `scope` and `component` naming convention, which is useful when configuring [query pipelines](https://docs.coveo.com/en/180/) and [query filters](https://docs.coveo.com/en/2114/) and associating them with your integration, or you can customize how search results appear in your Virtual Agent.

. [Configure your query pipeline](https://docs.coveo.com/en/3137#configure-your-query-pipeline).

. To maximize the relevance of search results returned by Coveo in your Virtual Agent, in the [Coveo Administration Console](https://docs.coveo.com/en/183/):

.. [Create an Automatic Relevance Tuning (ART) model](https://docs.coveo.com/en/3397/).

.. [Associate your model with the desired query pipeline](https://docs.coveo.com/en/l1ca1038/), and while doing so, check the **Comply with Intelligent Term Detection (ITD)** box.

## Configure your query pipeline

Once you've added Coveo for ServiceNow to your Virtual Agent, you must link your integration to a [query pipeline](https://docs.coveo.com/en/3198/) in your Coveo organization.

. In the [Coveo Administration Console](https://docs.coveo.com/en/183/), on the [**Query Pipelines**](https://platform.cloud.coveo.com/admin/#/orgid/search/pipelines/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/search/pipelines/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/search/pipelines/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/search/pipelines/)) page:

** To use an existing pipeline, select it, and then click **More** > **Edit** in the Action bar.

** [Create a new pipeline](https://docs.coveo.com/en/1791/) for the Virtual Agent to use.

. In the [**Add/Edit a Query Pipeline**](https://platform.cloud.coveo.com/admin/#/orgid/search/pipelines/new) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/search/pipelines/new) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/search/pipelines/new) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/search/pipelines/new)) panel, [create a condition](https://docs.coveo.com/en/1959#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](https://docs.coveo.com/en/3198#establish-a-widget-naming-convention) in the [`init` function](https://docs.coveo.com/en/3137#init-function), enter `ServiceNow`.

** If you provided [`scope` and `component` values](https://docs.coveo.com/en/3198#establish-a-widget-naming-convention), 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.

To customize how the results appear, you can pass a [`CoveoVirtualAgentResultsRenderer`](https://docs.coveo.com/en/3137#coveovirtualagentresultsrenderer-object-type) instance with a custom template as an optional third argument when calling the [`init` function](https://docs.coveo.com/en/3137#init-function) method on your [`CoveoVirtualAgent`](https://docs.coveo.com/en/3137#coveovirtualagent-object-type) instance.

To set a custom template on a `CoveoVirtualAgentResultsRenderer` instance, use the [`setTemplate`](https://docs.coveo.com/en/3137#settemplate-function) 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.

```javascript
(function execute() {
  var resultRenderer = new CoveoVirtualAgentResultsRenderer();
  var template = +++{% raw %}+'<div><a href="{{clickUri}}" onclick="{{logClickEvent}}"></a>{{raw.author}} - {{title}}</div>'+{% endraw %}+;
  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

. [Access the **Script Output** bot-response component](#scriptoutput) of the Virtual Agent topic in which you integrated Coveo.

. Modify the **Script Response Message** as required.
Refer to the [Reference](https://docs.coveo.com/en/3137#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](https://docs.coveo.com/en/3137#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:**

. `scope` (string, optional): The scope under which you want to categorize the function.
This parameter work similarly to the [Scope widget option](https://docs.coveo.com/en/3198#establish-a-widget-naming-convention).

. `component` (string, optional): The component under which you want to categorize the function.
This parameter work similarly to the [Component widget option](https://docs.coveo.com/en/3198#establish-a-widget-naming-convention).

. `resultRenderer` (function, optional): To customize how the search results appear in the Virtual Agent, this function passes a [`CoveoVirtualAgentResultsRenderer`](https://docs.coveo.com/en/3137#coveovirtualagentresultsrenderer-object-type) 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`](https://docs.coveo.com/en/3137#getsearchresults-function), and returns a [`MultiPartOutMsg`](https://community.servicenow.com/community?id=community_question&sys_id=cc26056fdb72af409540e15b8a9619c3) to be displayed in the Virtual Agent.
The query results are also saved in the Virtual Agent for more use (see [Virtual Agent Scripts](https://www.servicenow.com/docs/bundle/zurich-conversational-interfaces/page/administer/virtual-agent/concept/virtual-agent-scripts.html)).
For example, you could reuse the initial end user input in a script later in the conversation.

**Parameters:**

. {blank}
`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](https://docs.coveo.com/en/3137#integrate-coveo-for-service-now-in-the-virtual-agent)).

. {blank}
`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](https://docs.coveo.com/en/2081/)).

#### 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:**

. {blank}
`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](https://docs.coveo.com/en/3137#integrate-coveo-for-service-now-in-the-virtual-agent)).

. {blank}
`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](https://docs.coveo.com/en/2081/)).

#### getRenderer (function)

The `getRenderer` function returns the `resultRenderer`.

#### getVisitorId (function)

The `getVisitorId` function returns the [visitor ID](https://docs.coveo.com/en/273/), 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`](https://docs.coveo.com/en/3137#settemplate-function), [`setNumberOfResults`](https://docs.coveo.com/en/3137#setnumberofresults-function), etc.).

You can pass an instance of this object in the desired state as an optional third parameter when calling the [`init`](https://docs.coveo.com/en/3137#init-function) function of a [`CoveoVirtualAgent`](https://docs.coveo.com/en/3137#coveovirtualagent-object-type) 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](http://mustache.github.io/mustache.5.html) to display dynamic query result field values (for example, `{% raw %}{{raw.myfield}}{% endraw %}`).

**Important:** Ensure that your custom result template includes a result link, that is, an `a` tag whose `href` attribute is set to `+{% raw %}{{clickUri}}{% endraw %}+` and whose `onclick` attribute is set to `+{% raw %}{{logClickEvent}}{% endraw %}+`.
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:**

. `results` (object): The query results (see [Query response properties](https://docs.coveo.com/en/13#operation/searchUsingPost-response-Responses)).
This information is passed by [`CoveoVirtualAgent`](https://docs.coveo.com/en/3137#coveovirtualagent-object-type).

. `params` (object): The context of the renderer, that is, information on how the results were retrieved.
This information is passed by [`CoveoVirtualAgent`](https://docs.coveo.com/en/3137#coveovirtualagent-object-type).

## What's next?

[Configure query filters](https://docs.coveo.com/en/2114/) to ensure that the Coveo for ServiceNow components you configured in your public-facing and internal portals only return [items](https://docs.coveo.com/en/210/) from appropriate subsets of your [Coveo organization](https://docs.coveo.com/en/185/)’s [indexed](https://docs.coveo.com/en/204/) content.