Coveo for Sitecore 5 is now available!

Upgrading from August 2019 (4.1.734.71) to March 2020 (4.1.735.153)

For the best Coveo for Sitecore experience, always follow the Best Practices When Upgrading Coveo for Sitecore.

This section describes how to upgrade Coveo for Sitecore 4.1 from the August 2019 to the March 2020 release.

Step 1: Upgrade Coveo Services

  1. Ensure you have the latest version of Coveo Enterprise Search (CES 7.0.9434.6). If necessary, proceed as follows:
    1. Install the September 2018 release of Coveo Enterprise Search 7.0 x64 (7.0.9434) for Sitecore.
    2. Install the hotfix for the September 2018 release of Coveo Enterprise Search (CES 7.0.9434.6).

    Although you may refer to Upgrading CES for general instructions on how to upgrade CES, you must use the Coveo for Sitecore specific installation files which can be downloaded on the Coveo for Sitecore Downloads page.

  2. Ensure you have installed the August 2017 release of the Coveo Search API (8.0.1168).

Step 2: Upgrade Coveo for Sitecore

Please, ensure that the Microsoft MVC security update MS14-059 is installed on every Sitecore host in your environment.

If you’re using the Coveo Admin Service in secure mode, please read this notice before installing the package.

In the Coveo.SearchProvider.config file, make sure that the AdminServiceUri value uses the same host name as the one specified in the certificate. If you’re using a different host name, such as localhost, you might get the error below when installing the package.

The remote certificate is invalid according to the validation procedure.
...
[WebException: The underlying connection was closed: Could not establish trust relationship for the SSL/TLS secure channel.]
...
[SecurityNegotiationException: Could not establish trust relationship for the SSL/TLS secure channel with authority 'localhost'.]
  1. Log into the Sitecore Desktop.

  2. Access the Installation Wizard (Sitecore Start Menu > Development Tools > Installation Wizard).
  3. Upload and install the Coveo for Sitecore XX 4.1.735.153 package. You can find it in Downloads.
  4. When prompted to overwrite files, click Yes to all.
  5. When prompted to overwrite items, select Overwrite, then click Apply to all.

    You might be prompted twice with this question. Select the Overwrite option and click Apply to all both times.

  6. Once the installation is completed, make sure that you restart both the Sitecore client and server.

Step 3: Manually Update the Coveo Configuration Files

The Coveo configuration files are located in the Website\App_Config\Include\Coveo folder. When upgrading, you must compare the changes to the .example files from your current Coveo for Sitecore version with the ones in the build you’re upgrading to. Then, you can merge these changes into your current configuration files. This method allows you to keep your own customization intact, while still benefiting from the latest enhancements brought in the product. You can use a merge tool such as WinMerge to accomplish this.

In further detail, here are the modifications that you must perform to the configuration files resulting from the feature changes between the previous and current Coveo for Sitecore releases:

Coveo.SearchProvider.Rest.config

Sitecore 7 and 8

The <preprocessRequest> element below has been added as a child of the <pipelines> element to ensure that requests targeting the REST endpoint can handle special characters.

<preprocessRequest>
  <!-- This processor is required to ensure that requests targeting the REST endpoint can handle special characters. -->
  <processor patch:instead="processor[@type = 'Sitecore.Pipelines.PreprocessRequest.SuppressFormValidation, Sitecore.Kernel']" type="Coveo.SearchProvider.Rest.Processors.PreprocessRequest.SuppressFormValidation, Coveo.SearchProvider.Rest" >
    <urlPaths hint="list:AddUrlPath">
      <urlPath>/coveo/rest/</urlPath>
      <urlPath>/sitecore/admin/</urlPath>
      <urlPath>/sitecore/shell/</urlPath>
      <urlPath>/-/speak/request/</urlPath>
    </urlPaths>
  </processor>
</preprocessRequest>

Coveo.UI.Controls.Specific.config

Sitecore 8 and 9

The <pipelines> element below has been added as a child of the <sitecore> element.

<pipelines>
  <group name="itemProvider" groupName="itemProvider">
    <pipelines>
      <addFromTemplate>
        <processor type="Coveo.SearchProvider.Processors.UIResolveBranchRenderingDataSourcesProcessor, Coveo.SearchProvider" >
          <TemplatesToExpand hint="list">
            <coveoExampleSearchPage>{0555887D-AB12-46E6-8EA8-93D2E6ED3CB4}</coveoExampleSearchPage>
          </TemplatesToExpand>
        </processor>
      </addFromTemplate>
    </pipelines>
  </group>
</pipelines>

This addition tells Sitecore to call the new UIResolveBranchRenderingDataSourcesProcessor processor so that the creation of a new Example Search Page using the Insert Options feature works correctly.

Step 4: Update to the Default Frame View

The Default Frame.cshtml view file has been changed. Near the top of the file, the lines below have been inverted:

@Html.Sitecore().Placeholder("coveo-ui-searchbox-settings")
@Html.Sitecore().Placeholder("coveo-ui-searchbox")

The coveo-ui-searchbox placeholder now comes first. You might want to apply these changes to custom renderings based on the Default Frame.cshtml view file.

Step 5: Publish Your Site

In the Sitecore Content Editor, perform a publish site action. This ensures any changes related to Coveo components in the upgrade are published to the web database.

Step 1: Upgrade Coveo for Sitecore

Please, ensure that the Microsoft MVC security update MS14-059 is installed on every Sitecore host in your environment.

  1. Log into the Sitecore Desktop.
  2. Access the Installation Wizard (Sitecore Start Menu > Development Tools > Installation Wizard).
  3. Upload and install the Coveo for Sitecore XX 4.1.735.153 package. You can find it in Downloads.
  4. When prompted to overwrite files, click Yes to all.
  5. When prompted to overwrite items, select Overwrite, then click Apply to all.

    You might be prompted twice with this question. Select the Overwrite option and click Apply to all both times.

  6. Once the installation is completed, make sure that you restart both the Sitecore client and server.

Step 2: Manually Update the Coveo Configuration Files

The Coveo configuration files are located in the App_Config\Include\Coveo folder. When upgrading, you must compare the changes to the .example files from your current Coveo for Sitecore version with the ones in the build you’re upgrading to. Then, you can merge these changes into your current configuration files. This method allows you to keep your own customization intact, while still benefiting from the latest enhancements brought in the product. You can use a merge tool such as WinMerge to accomplish this.

In further detail, here are the modifications that you must perform to the configuration files resulting from the feature changes between the previous and current Coveo for Sitecore releases:

Coveo.SearchProvider.Rest.config

Sitecore 7 and 8

The <preprocessRequest> element below has been added as a child of the <pipelines> element to ensure that requests targeting the REST endpoint can handle special characters.

<preprocessRequest>
  <!-- This processor is required to ensure that requests targeting the REST endpoint can handle special characters. -->
  <processor patch:instead="processor[@type = 'Sitecore.Pipelines.PreprocessRequest.SuppressFormValidation, Sitecore.Kernel']" type="Coveo.SearchProvider.Rest.Processors.PreprocessRequest.SuppressFormValidation, Coveo.SearchProvider.Rest" >
    <urlPaths hint="list:AddUrlPath">
      <urlPath>/coveo/rest/</urlPath>
      <urlPath>/sitecore/admin/</urlPath>
      <urlPath>/sitecore/shell/</urlPath>
      <urlPath>/-/speak/request/</urlPath>
    </urlPaths>
  </processor>
</preprocessRequest>

Coveo.UI.Controls.Specific.config

Sitecore 8 and 9

The <pipelines> element below has been added as a child of the <sitecore> element.

<pipelines>
  <group name="itemProvider" groupName="itemProvider">
    <pipelines>
      <addFromTemplate>
        <processor type="Coveo.SearchProvider.Processors.UIResolveBranchRenderingDataSourcesProcessor, Coveo.SearchProvider" >
          <TemplatesToExpand hint="list">
            <coveoExampleSearchPage>{0555887D-AB12-46E6-8EA8-93D2E6ED3CB4}</coveoExampleSearchPage>
          </TemplatesToExpand>
        </processor>
      </addFromTemplate>
    </pipelines>
  </group>
</pipelines>

This addition tells Sitecore to call the new UIResolveBranchRenderingDataSourcesProcessor processor so that the creation of a new Example Search Page using the Insert Options feature works correctly.

Step 3: Update to the Default Frame View

The Default Frame.cshtml view file has been changed. Near the top of the file, the lines below have been inverted:

@Html.Sitecore().Placeholder("coveo-ui-searchbox-settings")
@Html.Sitecore().Placeholder("coveo-ui-searchbox")

The coveo-ui-searchbox placeholder now comes first. You might want to apply these changes to custom renderings based on the Default Frame.cshtml view file.

Step 4: Publish Your Site

In the Sitecore Content Editor, perform a publish site action. This ensures any changes related to Coveo components in the upgrade are published to the web database.

A Main search interface data source option has been added to the Coveo Recommendations Hive rendering and the Initialize Recommendations.cshtml file has been modified. If you have created a custom component by duplicating the Coveo Recommendations rendering, you might want to consider updating your custom component.

What's Next for Me?