usageanalytics.coveo.com endpoint deprecation

This is for:

Developer System Administrator

The usageanalytics.coveo.com endpoint is being deprecated. Beginning December 9, 2024, all calls to this endpoint will fail, your usage analytics will no longer be recorded, and the relevance of your search results will be impacted.

Coveo strongly recommends that all Coveo for Sitecore customers upgrade to the latest version and migrate to organization endpoints. Upgrading to the latest Coveo for Sitecore release simplifies the transition to organization endpoints and ensures that your instance is using the most up-to-date endpoints, features, and improvements.

Tip

The multi-release upgrade procedure speeds up the upgrade process.

If an immediate upgrade to the latest release of Coveo for Sitecore isn’t feasible, refer to the instructions associated with your current version of Coveo for Sitecore below to ensure you no longer use deprecated endpoints.

May 9, 2023 (5.0.1227.1) or October 23, 2023 (5.0.1277.4)

You’re not using the deprecated analytics endpoint, so no action is required.

However, Coveo strongly recommends that you upgrade to the latest version. Follow all upgrade steps including the organization endpoints migration steps.

September 18, 2020 (5.0.788.5) to February 15, 2023 (5.0.1202.1)

Short of upgrading to the latest release and enabling organization endpoints, ensure you’re using non-deprecated endpoints in your configuration files.

  1. In <SITECORE_INSTANCE_ROOT>\App_Config\Include\Coveo\Coveo.CloudPlatformClient.Custom.config, make sure that the <cloudPlatformUri> value is one of the following:

    For US East region organizations:

    <cloudPlatformUri>https://platform.cloud.coveo.com</cloudPlatformUri>

    If your Coveo organization uses regional endpoints, make sure you’re using the relevant region-specific endpoint (for example, https://platform-eu.cloud.coveo.com).

  2. In <SITECORE_INSTANCE_ROOT>\App_Config\Include\Coveo\Coveo.SearchProvider.Rest.Custom.config, make sure that the <analyticsUri> value is one of the following:

    For US East region organizations:

    <analyticsUri>https://analytics.cloud.coveo.com/rest/ua</analyticsUri>

    If your Coveo organization uses regional endpoints, make sure you’re using the relevant region-specific endpoint (for example, https://analytics-au.cloud.coveo.com/rest/ua).

Note

You can use PowerShell configuration and activation scripts to make these changes in your Sitecore instance.

Configuring

This function configures Coveo for Sitecore by applying the passed parameters values on the corresponding configuration files. It can be called either to fully or partially configure the instance.

function Configure-CoveoForSitecorePackage([Parameter(Mandatory=$true)]
                                           [string] $SitecoreInstanceUrl,
                                           [string] $CoveoForSitecoreApiVersion = "v1",
                                           [string] $OrganizationId,
                                           [string] $ConfigApiKey,
                                           [string] $SearchApiKey,
                                           [boolean] $DisableSourceCreation = $false,
                                           [string] $CoveoSitecoreUsername,
                                           [string] $CoveoSitecorePassword,
                                           [string] $DocumentOptionsBodyIndexing = "Rich",
                                           [boolean] $DocumentOptionsIndexPermissions = $true,
                                           [string] $FarmName,
                                           [boolean] $BypassCoveoForSitecoreProxy = $false,
                                           [Parameter(Mandatory=$true)]
                                           [string] $ScriptSitecoreUsername,
                                           [Parameter(Mandatory=$true)]
                                           [string] $ScriptSitecorePassword,
                                           [string] $ApiEndpointUrl = "",
                                           [string] $IndexingEndpointUrl = "",
                                           [string] $PlatformEndpointUrl = "",
                                           [string] $UsageAnalyticsEndpointUrl = "")
{
    $ConfigureCoveoForSitecoreUrl = $SitecoreInstanceUrl + "/coveo/api/config/" + $CoveoForSitecoreApiVersion + "/configure"
    ​
    $Body = @{ }
    ​
    if (![string]::IsNullOrEmpty($OrganizationId)) {
        $Body.Organization = @{
            "OrganizationId" = $OrganizationId
            "ApiKey" = $ConfigApiKey
            "SearchApiKey" = $SearchApiKey
            "ApiEndpointUrl" = $ApiEndpointUrl
            "IndexingEndpointUrl" = $IndexingEndpointUrl
            "PlatformEndpointUrl" = $PlatformEndpointUrl
            "UsageAnalyticsEndpointUrl" = $UsageAnalyticsEndpointUrl
            "DisableSourceCreation" = $DisableSourceCreation
        }
        $Body.Proxy = @{
            "BypassCoveoForSitecoreProxy" = $BypassCoveoForSitecoreProxy
        }
        $Body.SitecoreCredentials = @{
            "Username" = $CoveoSitecoreUsername
            "Password" = $CoveoSitecorePassword
        }
        $Body.DocumentOptions = @{
            "BodyIndexing" = $DocumentOptionsBodyIndexing
            "IndexPermissions" = $DocumentOptionsIndexPermissions
        }
        $Body.Proxy = @{
            "BypassCoveoForSitecoreProxy" = $BypassCoveoForSitecoreProxy
        }
    }

    if (![string]::IsNullOrEmpty($FarmName)) {
        $Body.Farm = @{
            "Name" = $FarmName
        }
    }
    ​
    $BodyJson = $Body | ConvertTo-Json
    ​
    $m_Headers = @{
        "x-scUsername" = $ScriptSitecoreUsername
        "x-scPassword" = $ScriptSitecorePassword
    }
    ​
    Write-Host "Configuring the Coveo for Sitecore package... "
    Try {
        Invoke-RestMethod -Uri $ConfigureCoveoForSitecoreUrl -Method PUT -Body $BodyJson -Headers $m_Headers -ContentType "application/json"
        Write-Host "The Coveo for Sitecore package is now configured."
    }
    Catch {
        Write-Host "There was an error during your Coveo for Sitecore package configuration:"
        Write-Host $PSItem
    }
}

If Coveo configuration files still have the .config.example extension, Coveo for Sitecore isn’t activated. You can use the following function to activate Coveo for Sitecore.

Activating

This function activates Coveo for Sitecore by renaming the *.config.example files to *.config. Since this is a configuration change, it will restart your IIS application pool once the operation is completed.

function Activate-CoveoForSitecorePackage([Parameter(Mandatory=$true)]
                                          [string] $SitecoreInstanceUrl,
                                          [string] $CoveoForSitecoreApiVersion = "v1",
                                          [Parameter(Mandatory=$true)]
                                          [string] $ScriptSitecoreUsername,
                                          [Parameter(Mandatory=$true)]
                                          [string] $ScriptSitecorePassword)
{
    $ActivateCoveoForSitecoreUrl = $SitecoreInstanceUrl + "/coveo/api/config/" + $CoveoForSitecoreApiVersion + "/activate"
    ​
    $m_Headers = @{
        "x-scUsername" = $ScriptSitecoreUsername
        "x-scPassword" = $ScriptSitecorePassword
    }
    ​
    Write-Host "Activating the Coveo for Sitecore package... "
    ​
    Try {
        Invoke-RestMethod -Uri $ActivateCoveoForSitecoreUrl -Method POST -Headers $m_Headers -ContentType "application/json"
        Write-Host "The Coveo for Sitecore package is now activated."
    }
    Catch {
        Write-Host "There was an error during your Coveo for Sitecore package activation:"
        Write-Host $PSItem
    }
}
Usage examples

Once the previous functions are added to your PowerShell script tooling, you can use them to configure and activate Coveo for Sitecore. Here is an example of how to call them with the right parameters:

.\yourpowershellscriptfile.ps1
Configure-CoveoForSitecorePackage -SitecoreInstanceUrl <SITECORE_URL> -OrganizationId <ORGANIZATION_ID> -ConfigApiKey <API_KEY> -SearchApiKey <SEARCH_API_KEY> -CoveoSitecoreUsername <COVEO_USERNAME> -CoveoSitecorePassword <COVEO_PASSWORD> -ScriptSitecoreUsername <SCRIPT_USERNAME> -ScriptSitecorePassword <SCRIPT_PASSWORD> -PlatformEndpointUrl <PLATFORM_ENDPOINT_URL> -UsageAnalyticsEndpointUrl <USAGE_ANALYTICS_ENDPOINT_URL>
​
.\yourpowershellscriptfile.ps1
Activate-CoveoForSitecorePackage -SitecoreInstanceUrl <SITECORE_URL> -ScriptSitecoreUsername <SCRIPT_USERNAME> -ScriptSitecorePassword <SCRIPT_PASSWORD>

You need to replace:

  • <ORGANIZATION_ID> with the ID of your Coveo organization.

  • <API_KEY> with an unencrypted API key with the appropriate rights.

  • <SEARCH_API_KEY> with an unencrypted API key with the appropriate rights.

  • <COVEO_USERNAME> and <COVEO_PASSWORD> with the unencrypted credentials of a user that can read all the files that you want to index.

  • <SCRIPT_USERNAME> and <SCRIPT_PASSWORD> with the unencrypted credentials of a user that can modify the configuration files of your Sitecore instance.

  • <SITECORE_URL> with your Sitecore instance URL.

  • <PLATFORM_ENDPOINT_URL> with the URL of the Coveo Platform endpoint (that is, https://platform.cloud.coveo.com or the region-specific endpoint, like https://platform-eu.cloud.coveo.com, if applicable for your Coveo organization).

  • <USAGE_ANALYTICS_ENDPOINT_URL> with the URL of the usage analytics endpoint (that is, https://analytics.cloud.coveo.com/rest/ua or the region-specific endpoint, like https://analytics-au.cloud.coveo.com/rest/ua, if applicable for your Coveo organization).

Versions older than September 18, 2020 (5.0.788.5)

You’re using the deprecated analytics endpoint and your implementation is severely outdated.

Upgrade to the latest version of Coveo for Sitecore and follow the steps to migrate to organization endpoints.

If you’re using Coveo for Sitecore 4.0 or 4.1, identify your upgrade scenario and follow the related instructions to upgrade to the latest version of Coveo for Sitecore 5.