THIS IS ARCHIVED DOCUMENTATION

Using PowerShell to Configure and Activate Coveo for Sitecore

Coveo for Sitecore 4.1 (April 2018)

As of the April 2018 release of Coveo for Sitecore, you can silently configure and activate Coveo for Sitecore using Swagger (see Silently Activating Coveo for Sitecore).

In this article, you will learn how to use a PowerShell script that does this for you, which can be useful when automating package installation or upgrade.

Configuring Coveo for Sitecore

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.

As long as the configuration files have the *.config.example extension, Coveo for Sitecore won’t be activated (see Activating Coveo for Sitecore).

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

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

Activating Coveo for Sitecore

This function activates Coveo for Sitecore by renaming the \*.config.example files to \*.config. Since it’s 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 Example

Once these 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 <SitecoreUrl> -OrganizationId <myorganizationid> -ConfigApiKey <ApiKey> -SearchApiKey <SearchApiKey> -CoveoSitecoreUsername <CoveoUsername> -CoveoSitecorePassword <CoveoPassword> -ScriptSitecoreUsername <ScriptUsername> -ScriptSitecorePassword <ScriptPassword>

.\yourpowershellscriptfile.ps1
Activate-CoveoForSitecorePackage -SitecoreInstanceUrl <SitecoreUrl> -ScriptSitecoreUsername <ScriptUsername> -ScriptSitecorePassword <ScriptPassword>

You need to replace:

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

  • <ApiKey> with an API key with the appropriate rights (see Silently Activating Coveo for Sitecore).

  • <SearchApiKey> with an API key with the appropriate rights (see Silently Activating Coveo for Sitecore).

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

  • <ScriptUsername> and <ScriptPassword> with the credentials of a user that can modify the configuration files of your Sitecore instance.

    The default credentials in Sitecore are sitecore\admin for the username and b for its password.

  • <SitecoreUrl> with your Sitecore instance URL.

What's next for me?