Activate silently

This is for:

Developer System Administrator

In some circumstances, for example when creating many Sitecore servers, you’ll want to silently configure and activate Coveo for Sitecore. This can be done using the REST API services that Coveo for Sitecore deploys to set the different configurations, instead of doing so via the Command Center activation page. The interactive Swagger UI documentation for these services is available at https://<INSTANCE_HOSTNAME>/coveo/api/config/docs/index.

Swagger UI for Configuration and Activation services | Coveo

Prerequisites

To perform the configuration and activation of Coveo for Sitecore via the REST API services, you need the following:

  • A running instance of Sitecore with the Coveo for Sitecore package installed, and on which you have administrator access.

  • A Coveo organization.

    You’ll need the organizationId which can be retrieved in the URL of your Coveo organization.

    OrganizationId shown in the URL of your Coveo organization | Coveo

    If you don’t have access to an existing organization, create a trial organization using the Coveo Platform API Create organization Swagger UI page for your region: US | CA | EU | AU

    Important

    In the organizationTemplate field, you need to specify a Coveo for Sitecore-specific template value. The options are:

    • SitecoreCloudProEditionTrial for the Pro edition.

    • SitecoreCloudTrialEdition for the Enterprise edition.

  • Two API keys:

    • SearchApiKey – for search activities.

    • ApiKey – for general organization configuration activities.

      To create the SearchApiKey

      1. Access the Coveo Platform API Create API key Swagger UI page for your region: US | CA | EU | AU

      2. Authorize the Swagger UI to perform the upcoming request.

        1. At the top-right of the screen, click Authorize.

        2. Authenticate into the Coveo Platform as an administrator.

      3. In the Parameters section of the Swagger UI:

        • In the organizationId field, enter your organizationId.

        • In the apiKeyTemplateId field, enter SitecoreCloudSearch.

          Note

          Creating the key based on the SitecoreCloudSearch template ensures adherence to the principle of minimum privileges and provides future-proofing by transparently applying any changes made to the template privileges to existing API keys.

      4. Copy the following JSON and paste it in the request body:

        {
  "displayName": "SearchApiKey",
  "enabled": true
}

      5. Click Execute.

      6. Retrieve the API key value from the response body and store it securely.

      To create the ApiKey

      1. Access the Coveo Platform API Create API key Swagger UI page for your region: US | CA | EU | AU

      2. If necessary, authorize the Swagger UI to perform the upcoming request.

        1. At the top-right of the screen, click Authorize.

        2. Authenticate into the Coveo Platform as an administrator.

      3. In the Parameters section of the Swagger UI:

      4. In the apiKeyTemplateId field, enter SitecoreCloudConfiguration.

        Note

        Creating the key based on the SitecoreCloudConfiguration template ensures adherence to the principle of minimum privileges and provides future-proofing by transparently applying any changes made to the template privileges to existing API keys.

      5. Copy the following JSON and paste it in the request body:

        {
  "displayName": "ApiKey",
  "enabled": true
}

      6. Click Execute.

      7. Retrieve the API key value from the response body and store it securely.

      Important

      Sitecore on Azure

      Azure’s Web Application Firewall (WAF) may block Coveo query network requests that trigger OWASP rules. You might need to disable or customize Azure WAF rules to allow Coveo for Sitecore network requests (see Azure Web Application Firewall triggered rules block Coveo for Sitecore’s communication on Content Delivery servers).

Configure and activate Coveo for Sitecore

This process requires the following steps:

Step 1 - Retrieve your organization endpoints

The request you’ll perform will retrieve the search, admin, and analytics organization endpoints you can use in step 2 to configure Coveo for Sitecore. You need the October 23, 2023 release (5.0.1277.4) or later to be able to configure Coveo for Sitecore with organization endpoints.

Organization endpoints API request | Coveo

  1. Access the Coveo Platform API Get organization global configuration Swagger UI page for your region: US | CA | EU | AU

  2. If necessary, authorize the Swagger UI to perform the upcoming request.

    1. At the top-right of the screen, click Authorize.

    2. Authenticate into the Coveo Platform as an administrator.

  3. Enter your organizationId and click Execute.

  4. Copy the response body so that you can specify these endpoints in the next step.

Step 2 - Configure

In this step, you’ll use the REST API bundled in Coveo for Sitecore to configure communication between Sitecore and the Coveo Platform, and to set application parameters. For example, you’ll tell Coveo for Sitecore which Coveo organization to index your items in, the Coveo Platform API endpoint URLs and keys to use for indexing and search activities.

  1. Open the https://<INSTANCE_HOSTNAME>/coveo/api/config/docs/index#!/ConfigureInstance/ConfigureInstanceV1_Update Swagger UI page in your browser.

  2. In the Value field, set the JSON body parameter values for the PUT request. You can use the example below as a template, and replace the values with your own.

    Example
    {
  "Organization": {
    "OrganizationId": "mdteste72n3veh",
    "ApiKey": "xxe116ab99-6d42-41cc-95tr-7b25bb29ad87",
    "SearchApiKey": "xx62f4737a-c29p-4f9e-b2x5-6b19012ac8c1",
    "GeneralPlatformEndpointUrl": "https://platform-ca.cloud.coveo.com",
    "IndexingEndpointUrl": "https://api-ca.cloud.coveo.com/push",
    "PlatformEndpointUrl": "mdteste72n3veh.admin.org.coveo.com", 1
    "SearchEndpointUrl": "mdteste72n3veh.org.coveo.com", 2
    "UsageAnalyticsEndpointUrl": "mdteste72n3veh.analytics.org.coveo.com", 3
    "DisableSourceCreation": false 4
  },
  "SitecoreCredentials": {
    "Username": "sitecore\\admin", 5
    "Password": "a46WW!2d"
  },
  "DocumentOptions": {
    "BodyIndexing": "Rich", 6
    "IndexPermissions": true 7
  },
  "Farm": {
    "Name": "ABCproduction" 8
  },
  "Proxy": {
    "BypassCoveoForSitecoreProxy": false 9
  }
}
    1 Use the adminDns value from the response body of the Get organization global configuration request.
    2 Use the distributedDns value from the response body of the Get organization global configuration request.
    3 Use the analyticsDns value from the response body of the Get organization global configuration request.
    4 The value is optional. False is the default value. See Basic configuration settings for more information on this parameter.
    5 Ensure you escape the domain-username backslash in the Username field.
    6 The value is optional. The default value is Rich, which means that the rendered HTML of your Sitecore items will be indexed.
    7 The value is optional. The default value is true, which means that the permissions on your Sitecore items will be indexed.
    8 See the farmName property in the Basic configuration settings table for more information on this parameter.
    9 The value is optional. False is the default value. See restEndpointConfiguration section settings for more information on this parameter.

Coveo for Sitecore Swagger Configure request

  1. Specify the administrator’s user credentials in the x-scUsername and x-scPassword headers to authenticate the request.

  2. Click Try it out. If the request is successful, you’ll see a 204 status code.

Step 3 - Activate

In this step, you’ll use the REST API bundled in Coveo for Sitecore to activate Coveo for Sitecore on the Sitecore instance. This will rename the base .example Coveo for Sitecore configuration files to enable them.

It will also validate that all values required in the configuration step have been set.

Coveo for Sitecore Swagger Configure call

  1. Open the https://<INSTANCE_HOSTNAME>/coveo/api/config/docs/index#!/ActivateInstance/ActivateInstanceV1_Post Swagger UI page in your browser.

  2. Specify the administrator’s user credentials in the x-scUsername and x-scPassword headers to authenticate the request.

  3. Click Try it out. If the request is successful, you’ll see a 200 status code and a response body containing the list of enabled configuration files.