Setting the Search Hub

In a Coveo-powered solution, each distinct search interface should be identified by its own unique search hub value (also called origin level 1).

All queries and usage analytics events that originate from a given search interface will normally bear the corresponding search hub value. It’s vital that you set this value properly, as it allows you to implement condition-based query pipeline routing, filter data in usage analytics reports, and most importantly, leverage Coveo Machine Learning (Coveo ML) features in your solution.

Your Coveo-powered solution includes the following search interfaces:

Search interface description	Search hub
A customer-facing community search page	`ACMECommunitySearch`
A customer-facing case deflection panel	`ACMECustomerCaseDeflection`
An internal support agent insight panel	`ACMEAgentInsightPanel`

In your Coveo organization, you create a distinct query pipeline for each search interface:

Query pipeline name	Condition
Community Search	`when $searchHub is ACMECommunitySearch`
Case Deflection Panel	`when $searchHub is ACMECustomerCaseDeflection`
Insight Panel	`when $searchHub is ACMEAgentInsightPanel`

This will always route search requests originating from your customer-facing community search page to the Community Search pipeline, and so on for each of your other search interfaces.

You also associate a Coveo Machine Learning (Coveo ML) Automatic Relevance Tuning (ART) and Query Suggestions (QS) model to each pipeline.

Since these models use the searchHub value as a default filter for their output, the actions performed in a specific search interface (e.g., ACMECommunitySearch) will only influence the output of the models in that same interface. For example, actions performed by customer end users in the ACMECommunitySearch interface won’t affect the query suggestions provided to agent end users in the ACMEInsightPanel interface, nor those provided to customer end users in the ACMECaseDeflectionPanel interface.

There are three ways to set the search hub:

Enforce it in the search token (recommended)
Set it with the Analytics component
Set it when configuring the search endpoint

Enforcing the Search Hub in the Search Token (Recommended)

If you’re using search token authentication in your Coveo-powered solution, the most secure way to set the search hub of each search interface is to enforce it in the search token.

To do so, set the searchHub request body property to the desired value when requesting the search token.

Requesting a search token impersonating the asmith@example.com security identity and enforcing the ACMEAgentInsightPanel search hub.

POST https://platform.cloud.coveo.com/rest/search/v2/token HTTP/1.1
 
Content-Type: application/json
Accept: application/json
Authorization: Bearer **********-****-****-****-************

Payload

{
  "searchHub": "ACMEAgentInsightPanel",
  "userIds": [
    {
      "name": "asmith@example.com",
      "provider": "Email Security Provider",
    }
  ]
}

200 OK response body

{
  "token": "eyJhbGciOiJIUzI1NiJ9.eyJzZWFyY2hIdWI[...]"
}

The decoded JSON web token (JWT) contains the search hub information:

{
  "searchHub": "ACMEInsightPanel",
  "v8": true,
  "organization": "mycoveoorganization",
  "userIds": [
    {
      "provider": "Email Security Provider",
      "name": "asmith@example.com",
      "type": "User"
    }
  ],
  "roles": [
    "queryExecutor"
  ],
  "exp": 1572023637,
  "iat": 1571937237
}

In some scenarios, such as when using the Coveo for Salesforce product integration, search token authentication is already implemented, and the search hub is automatically enforced in the search token.

See your specific Coveo product integration documentation for more information.

Setting the Search Hub with the Analytics Component

In a Coveo JavaScript Search Framework interface, you can use the searchHub option of the Analytics component to set the search hub to the desired value.

Setting the search hub in this fashion is less secure than enforcing it in the search token, but this is a legitimate method when you’re using API key authentication across all of the search interfaces in your solution (i.e., when all of your content is public).

Setting the search hub to ACMECommunitySearch using the searchHub option of the Analytics component.

<div class="CoveoSearchInterface">
  <div class="CoveoAnalytics" data-search-hub="ACMECommunitySearch"></div>
  <!-- ... -->
</div>

If a search hub is specified in the search token and you also set the searchHub option of the Analytics component in a JavaScript Search Framework interface, the search token-enforced search hub prevails.

You should enforce the search hub in the search token when you want to implement features that require the search hub to be set securely, such as Coveo ML QS.

If you set the search hub with the Analytics component, its value can easily be changed by an end user. By contrast, if you’re only using search tokens and enforcing the search hub in those tokens across your solution, then there’s no way to tamper with the search hub (you can change it as much as you want in the interface, or make your own Search API requests, and the token will always override whatever you set).

For example, the query suggestions that are returned in your agent insight panel sometimes contain sensitive customer information. Any end user who knows the search hub for the agent insight panel (ACMEAgentInsightPanel) can go to your community search page, copy the public API key for authentication, and send requests to the Search API using the agent insight panel search hub, giving them access to your sensitive information.

Setting the Search Hub When Configuring the Search Endpoint

You can pass queryStringArguments to set the search hub when configuring the search endpoint (see Class SearchEndpoint).

This isn’t as secure as enforcing the search hub in the search token. You should only use this method when both of the following are true:

You’re using API key authentication across all of the search interfaces in your solution (i.e., all of your content is public).
You don’t want to include an Analytics component in a search interface (e.g., you’re using a standalone search box), but you still need to configure the search hub properly.

document.addEventListener("DOMContentLoaded", () => {
  Coveo.SearchEndpoint.configureCloudV2Endpoint(
    "mycoveoorganization",
    "xxxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "https://platform.cloud.coveo.com/rest/search",
    {
      "queryStringArguments": {
        "searchHub": "ACMECommunitySearch"
      }
    });
})

You should enforce the search hub in the search token when you want to implement features that require the search hub to be set securely, such as Coveo ML QS.

If you set the search hub when configuring the search endpoint, its value can easily be changed by an end user. By contrast, if you’re only using search tokens and enforcing the search hub in those tokens across your solution, then there’s no way to tamper with the search hub (you can change it as much as you want in the interface, or make your own Search API requests, and the token will always override whatever you set).