Upgrading from September 2016 to October 2016

THIS IS ARCHIVED DOCUMENTATION

Upgrading from September 2016 to October 2016

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.0 from the September 2016 to the October 2016 release.

Step 1: Upgrade Coveo Services

Ensure that you have installed the September 2016 release of Coveo Enterprise Search (CES 7.0.8541). For more details, see Upgrading CES.
Ensure that you have installed the May 2016 release of the Coveo Search API (8.0.1130).

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 Coveo Search Provider Configuration File

Merging Your Modifications into the Configuration Files

Implement the Expanded Security Provider

The October 2016 release of Coveo for Sitecore introduces the new Expanded Security Provider, to improve the way securities handled by Coveo Cloud. While the previous security method is still supported, you’re encouraged to upgrade to the expanded security provider (see Upgrading to the Expanded Security Provider).

Add the Results per Page Component

The default search page of the October 2016 release of Coveo for Sitecore now comes with a results per page component, which is displayed at the bottom of your search page.

If you want, add it to your custom search pages.

Access the layout files of your custom search page.
1. For Web Forms, it should be a .ascx or .aspx file located under or near the <SITECORE_INSTANCE_ROOT>\Website\layouts folder.
2. For MVC, it should be a .cshtml file located under or near the <SITECORE_INSTANCE_ROOT>\Website\Views folder.
Locate the if condition of the Model.DisplayBottomPager section.

After this section, add the following code:

 <% if (Model.DisplayResultsPerPage) { %>
        <div class="CoveoResultsPerPage"></div>
 <% } %>

Save the file.

If you want to change the number shown in this component, see Coveo Component Results per Page.

Manually Modify the Configuration Files

The following modifications detail what has changed between the September 2016 and October 2016 releases in the .example files.

Rephrasing in Comments

Many of the comments in the .config files were rephrased to ease their understanding. Because this doesn’t affect logic nor do they present or remove features, they won’t be presented in this upgrade procedure.

`Coveo.SearchProvider.config`

In the <events timigLevel="custom"> node, add the following nodes:

<event name="coveo:config:cloudConnectionChanged">
  <handler type="Coveo.SearchProvider.Events.ExpandedPermissionsEventHandler, Coveo.SearchProviderBase" method="OnCloudConnectionChanged" />
</event>
<event name="coveo:indexing:afterSetupRequirements">
  <handler type="Coveo.SearchProvider.Events.ExpandedPermissionsEventHandler, Coveo.SearchProviderBase" method="OnAfterSetupRequirements" />
</event>

In the <event name="user:created"> node, add the following handler:

<handler type="Coveo.SearchProvider.Events.ExpandedPermissionsEventHandler, Coveo.SearchProviderBase" method="OnUserCreated" />

In the <event name="user:updated"> node, add the following handler:

<handler type="Coveo.SearchProvider.Events.ExpandedPermissionsEventHandler, Coveo.SearchProviderBase" method="OnUserUpdated" />

In the <event name="user:deleted"> node, add the following handler:

<handler type="Coveo.SearchProvider.Events.ExpandedPermissionsEventHandler, Coveo.SearchProviderBase" method="OnUserDeleted" />

Before the <event name="roles:usersAdded"> node, add the following nodes:

<event name="role:created">
  <handler type="Coveo.SearchProvider.Events.ExpandedPermissionsEventHandler, Coveo.SearchProviderBase" method="OnRoleCreated" />
  <handler type="Coveo.SearchProvider.Events.EntityEventHandler, Coveo.SearchProviderBase" method="OnRoleCreated"/>
</event>
  <event name="role:deleted">
    <handler type="Coveo.SearchProvider.Events.ExpandedPermissionsEventHandler, Coveo.SearchProviderBase" method="OnRoleDeleted" />
    <handler type="Coveo.SearchProvider.Events.EntityEventHandler, Coveo.SearchProviderBase" method="OnRoleDeleted"/>
</event>

In the <event name="roles:usersAdded"> node, add the following handler:

<handler type="Coveo.SearchProvider.Events.ExpandedPermissionsEventHandler, Coveo.SearchProviderBase" method="OnUsersAddedToRole" />

In the <event name="roles:usersRemoved"> node, add the following handler:

<handler type="Coveo.SearchProvider.Events.ExpandedPermissionsEventHandler, Coveo.SearchProviderBase" method="OnUsersRemovedFromRole" />

After the <event name="roles:usersRemoved"></event> node, add the following nodes:

<event name="roles:rolesAdded">
  <handler type="Coveo.SearchProvider.Events.ExpandedPermissionsEventHandler, Coveo.SearchProviderBase" method="OnRolesAddedToRoles" />
  <handler type="Coveo.SearchProvider.Events.EntityEventHandler, Coveo.SearchProviderBase" method="OnRolesAddedToRoles"/>
</event>
<event name="roles:rolesRemoved">
  <handler type="Coveo.SearchProvider.Events.ExpandedPermissionsEventHandler, Coveo.SearchProviderBase" method="OnRolesRemovedFromRoles" />
  <handler type="Coveo.SearchProvider.Events.EntityEventHandler, Coveo.SearchProviderBase" method="OnRolesRemovedFromRoles"/>
</event>

In the getContentEditorWarning node, add the following processor:

<!-- The CoveoRecommendationsWarningProcessor validates that the Coveo Machine Learning Recommendations can be used -->
<processor type="Coveo.SearchProvider.Processors.CoveoRecommendationsWarningProcessor, Coveo.SearchProvider" />

After the getContentEditorWarning node, add the following nodes:

<getPageEditorNotifications>
  <!-- The CoveoRecommendationsWarningProcessor validates that the Coveo Machine Learning Recommendations can be used -->
  <processor type="Coveo.SearchProvider.Processors.CoveoRecommendationsWarningProcessor, Coveo.SearchProvider" />
</getPageEditorNotifications>

At the end of the pipelines node, add the following nodes:

<initialize>
  <processor type="Coveo.SearchProvider.Processors.EnableTls12Processor, Coveo.SearchProviderBase" />
</initialize>

After the defaultIndexConfiguration node, add the following nodes:

<retryGroups>
  <throttlingAndTimeout type="Coveo.Framework.Utils.Rest.HttpWaitAndRetryGroup, Coveo.Framework">
    <retryStrategy type="Coveo.Framework.Utils.Rest.ConstantIntervalRetryStrategy">
      <numberOfRetry>1000</numberOfRetry>
      <interval>00:00:03</interval>
    </retryStrategy>
    <conditions hint="raw:AddCondition">
      <condition statusCodes="429|503|504" />
    </conditions>
  </throttlingAndTimeout>
</retryGroups>

At the beginning of the contentSearch node, add the following nodes:

Sitecore 7.5

<indexConfiguration>
  <indexUpdateStrategies>
    <coveoSyncMaster name="CoveoSyncMaster" ref="contentSearch/indexUpdateStrategies/syncMaster" />
    <coveoOnPublishEndAsync name="CoveoOnPublishEndAsync" ref="contentSearch/indexUpdateStrategies/onPublishEndAsync" />
  </indexUpdateStrategies>
</indexConfiguration>

Sitecore 7.2 only

<indexUpdateStrategies>
  <coveoSyncMaster name="CoveoSyncMaster" ref="contentSearch/indexUpdateStrategies/syncMaster" />
  <coveoOnPublishEndAsync name="CoveoOnPublishEndAsync" ref="contentSearch/indexUpdateStrategies/onPublishEndAsync" />
</indexUpdateStrategies>

In the <configuration ref="coveo/defaultIndexConfiguration"> node, add the following node:

<!-- Whether to push permissions when rebuilding the index. -->
<pushPermissionsOnRebuild>true</pushPermissionsOnRebuild>

In the strategies node of the Coveo_master_index, change the contentSearch/indexUpdateStrategies/syncMaster strategy to contentSearch/indexUpdateStrategies/coveoSyncMaster.

In the strategies node of the Coveo_web_index, change the contentSearch/indexUpdateStrategies/onPublishEndAsync strategy to contentSearch/indexUpdateStrategies/coveoOnPublishEndAsync.

`Coveo.SearchProvider.Custom.config`

In the defaultIndexConfiguration node, add the following nodes and comment:

<fieldMap>
  <fieldNames hint="raw:AddFieldByFieldName">
    <!-- This is an example of field.
         Supported attributes, fieldName: The field name.
                               isDisplayField: Whether the field should be displayed.
                               isFacet: Whether the field is set as facet.
                               isIncludedFreeText: Whether the field should be included in free text queries.
                               isMultiValue: Whether the field should be indexed as a many value field.
                               sortable: Whether the field is set as sortable.
         For more information, see: https://docs.coveo.com/en/811/coveo-for-sitecore-v4/changing-the-settings-of-sitecore-fields -->
    <!--
      <fieldType fieldName="theNewFieldToCreate" isMultiValue="true" settingType="Coveo.Framework.Configuration.FieldConfiguration, Coveo.Framework" />
    -->
  </fieldNames>
</fieldMap>

`Coveo.SearchProvider.Rest.Config`

The commented out processor of type Coveo.SearchProvider.Rest.Processors.GetSearchUserIdentities.AddUserMembers should now read as such:

<!-- This processor adds the expanded user mappings to the search identities. -->
<!--
<processor type="Coveo.SearchProvider.Rest.Processors.GetSearchUserIdentities.AddUserMappings, Coveo.SearchProvider.Rest" />
-->

In the pipelines node, after the getSearchUserIdentities node, add the following node:

<getUserMappings>
  <!-- This processor uses the e-mail address from the user profile to expand to an e-mail user identity. -->
  <processor type="Coveo.SearchProvider.Rest.Processors.GetUserMappings.AddSitecoreUserEmailIdentity, Coveo.SearchProvider.Rest" />
</getUserMappings>
<!-- The "getUserMembers" is exposed by Sitecore2's web service. Therefore, the "getUserMappings" pipeline
     should be used instead to control to which identities a Sitecore user identity is expanded. -->

The processor of type Coveo.Connectors.Sitecore2.SitecoreWebService.Pipelines.GetUserMembers.SitecoreEmailProcessor, Coveo.Connectors.Sitecore2.SitecoreWebService should now read as such:

<!-- This processor invokes the "getUserMappings" pipeline to expand a Sitecore user identity.
     Invoking the "getUserMappings" pipeline from here ensures a consistent user expansion between on-premises and Cloud deployments. -->
<processor type="Coveo.SearchProvider.Rest.Processors.Sitecore2.GetUserMembers.InvokeGetUserMappingsPipeline, Coveo.SearchProvider.Rest" />

After the httpRequestBegin pipeline, add the following nodes:

<httpRetry.SearchExceptionsHandler>
  <processor name="CoveoWaitAndRetryCleanUpCall" type="Coveo.Framework.Utils.Rest.HttpWaitAndRetry, Coveo.Framework">
    <retryGroups hint="list:AddGroup">
      <retryGroup name="SecurityProviderNotRegistered" type="Coveo.Framework.Utils.Rest.HttpWaitAndRetryGroup, Coveo.Framework">
        <retryStrategy type="Coveo.Framework.Utils.Rest.ConstantIntervalRetryStrategy">
          <numberOfRetry>20</numberOfRetry>
          <interval>00:00:30</interval>
        </retryStrategy>
        <conditions hint="raw:AddCondition">
          <condition statusCodes="400" responseMatch="SecurityProviderNotRegistered" />
        </conditions>
      </retryGroup>
      <group name="ThrottlingAndTimeout" ref="coveo/retryGroups/throttlingAndTimeout" />
    </retryGroups>
  </processor>
</httpRetry.SearchExceptionsHandler>

`Coveo.UI.Controls.config`

Remove the following nodes:

<preprocessRequest>
  <!-- This processor is required for Sitecore 7.0 update 4 and Sitecore 7.1 update 1. For other versions, this processor can be safely disabled. -->
  <processor patch:before="*[starts-with(@type,'Sitecore.Pipelines.PreprocessRequest.NormalizeRawUrl')]" mode="on" type="Coveo.UI.PipelineProcessors.PreprocessRequest.RewriteQueryStringProcessor, Coveo.UIBase" />
</preprocessRequest>

`SwitchMasterToWeb.Coveo.config`

At the beginning of the sitecore node, add the following nodes:

<coveo>
  <defaultIndexConfiguration>
    <skipFirstTimeSetupCheck>true</skipFirstTimeSetupCheck>
    <securityConfiguration>
      <skipSitecoreCredentialsUpdate>true</skipSitecoreCredentialsUpdate>
      <skipSitecoreLoginCheck>true</skipSitecoreLoginCheck>
    </securityConfiguration>
  </defaultIndexConfiguration>
</coveo>
<contentSearch>
  <indexUpdateStrategies>
    <coveoSyncMaster name="CoveoSyncMaster">
      <patch:attribute name="ref" value="contentSearch/indexUpdateStrategies/manual" />
    </coveoSyncMaster>
    <coveoOnPublishEndAsync name="CoveoOnPublishEndAsync">
      <patch:attribute name="ref" value="contentSearch/indexUpdateStrategies/manual" />
    </coveoOnPublishEndAsync>
  </indexUpdateStrategies>
  <configuration>
    <indexes>
      <index id="Coveo_master_index">
        <patch:delete />
      </index>
    </indexes>
  </configuration>
</contentSearch>