Upgrading from August 2018 to September 2018

THIS IS ARCHIVED DOCUMENTATION

Upgrading from August 2018 to September 2018

This is for:

Developer System Administrator

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

This section describes how to upgrade Coveo for Sitecore 4.1 from the August 2018 to the September 2018 release.

Step 1: Upgrade Coveo Services

Ensure that you have Coveo Enterprise Search (CES 7.0.9434). If necessary, install the September 2018 Coveo Enterprise Search 7.0 x64 (9434) for Sitecore.

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.
Ensure that you have installed the August 2017 release of the Coveo Search API (8.0.1168).

Step 2: Upgrade Coveo for Sitecore

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, 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'.]

Log into the Sitecore Desktop.
Access the Installation Wizard (Sitecore Start Menu > Development Tools > Installation Wizard).
Install the Coveo for Sitecore .zip package.
When prompted to overwrite files, click Yes to all.
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.
Once the installation is completed, make sure that you restart both the Sitecore client and server.

Step 3: Manually Update the Coveo Search Provider Configuration File

Merging Your Modifications Into the Configuration Files

Since upgrading Coveo for Sitecore modifies the Coveo Search Provider configuration files (Coveo.SearchProvider.config.example and Coveo.SearchProvider.Custom.config.example) with the latest fixes and enhancements, you need to manually merge these modifications into your current configuration files (Coveo.SearchProvider.config and Coveo.SearchProvider.Custom.config). 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 do that.

Step 1: Upgrade Coveo for Sitecore

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

Log into the Sitecore Desktop.
Access the Installation Wizard (Sitecore Start Menu > Development Tools > Installation Wizard).
Install the Coveo for Sitecore .zip package.
When prompted to overwrite files, click Yes to all.
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.
Once the installation is completed, make sure that you restart both the Sitecore client and server.

Step 2: Manually Update the Configuration Files

Merging Your Modifications Into the 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 WinMergeto 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.config`

The element below appears as an addition:

<setting name="Coveo.Indexing.PreferSourceSpecificFields" value="false" />

To keep the behavior of your instance unchanged, don’t add this line in your configuration.

For more details about isSourceSpecific and isExternal field attributes and their behavior, see Understanding The Coveo Search Provider Configuration File.

Locate the following element:

<exclude hint="list:AddExcludedField" ref="mandatory, don't delete" factory="excludedFieldsFactory" />

Immediately underneath that element, add the following element:

<include hint="list:AddIncludedField" />

`Coveo.SearchProvider.Custom.config`

In the fieldMap node, inside the first fieldNames element, in the opening comment, replace isExternal with isSourceSpecific.

<!--
     Most used option attributes:
       General options for all fields:
         isSourceSpecific: Defines whether this field should be translated (addition of the "f" prefix and the source name hash suffix).
-->

Step 3: Merging Changes to Coveo Hive Views in Your Custom .cshtml Files

As a result of bug SC-3113 being fixed (see Release Notes for September 2018), the following rendering .cshtml files have been modified:

\Website\Views\Coveo Hive\Resources\Coveo Search Resources.cshtml
\Website\Views\Coveo Hive\Search Boxes\Coveo Searchbox.cshtml
\Website\Views\Coveo Hive\Search Interfaces\Coveo Recommendations.cshtml
\Website\Views\Coveo Hive\Search Interfaces\Coveo Related Query.cshtml
\Website\Views\Coveo Hive\Search Interfaces\Coveo Search Interface.cshtml

This is a non-breaking change, so no action on your part is actually required.

However, if you’re using custom .cshtml files based on the files above, you might want to merge the changes into your custom files to have an error message rendered on your public site when critical Coveo Hive component errors occur.

Step 4: Merging Changes to Coveo Hive Views in Your Custom .cshtml Files

As a result of bug SC-3113 being fixed (see Release Notes for September 2018), the following rendering .cshtml files have been modified:

\Website\Views\Coveo Hive\Resources\Coveo Search Resources.cshtml
\Website\Views\Coveo Hive\Search Boxes\Coveo Searchbox.cshtml
\Website\Views\Coveo Hive\Search Interfaces\Coveo Recommendations.cshtml
\Website\Views\Coveo Hive\Search Interfaces\Coveo Related Query.cshtml
\Website\Views\Coveo Hive\Search Interfaces\Coveo Search Interface.cshtml

This is a non-breaking change, so no action on your part is actually required.

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.

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.