Configure and activate using the user interface

This is for:

Developer System Administrator

After installing Coveo for Sitecore, it must be configured and activated. The steps in this article let you link your Sitecore instance to a Coveo organization and perform indexing configurations.

Note

In some circumstances, for example in multi-server setups, you may prefer activating Coveo for Sitecore using PowerShell.

HIPAA organization prerequisites

To use Coveo for Sitecore with a Coveo HIPAA-compliant environment, you need to have a Coveo HIPAA Platform organization created for you. Then, you’ll have to perform a few extra configuration steps to get your Sitecore instance ready to link to that HIPAA organization.

If you don’t need a HIPAA-compliant environment, you may skip to the activation procedure right away.

To prepare for a Coveo for Sitecore with HIPAA organization activation

  1. Contact Coveo Sales to get a HIPAA organization created for you.

  2. If you had already activated Coveo for Sitecore on a non-HIPAA Coveo organization, you need to delete the following Coveo folders from your main Sitecore CM server:

    • <SITECORE_INSTANCE_ROOT>\App_Config\Include\Coveo

      Tip

      You may want to keep a backup of this folder which contains your custom configurations. You can integrate your custom configurations after activation.

    • <SITECORE_INSTANCE_ROOT>\App_Config\Modules\Coveo

  3. In the <SITECORE_INSTANCE_ROOT>\App_Config\Include\ folder, create a text file called Coveo.Cloud.Hipaa.config.

  4. In the Coveo.Cloud.Hipaa.config file, paste the snippet below and save your changes.

    <configuration xmlns:patch="http://www.sitecore.net/xmlconfig/">
 <sitecore>
   <settings>
     <setting name="Coveo.Cloud.AuthorizationEndpointUri" value="https://platformhipaa.cloud.coveo.com/oauth/authorize" />
     <setting name="Coveo.Cloud.IndexingEndpointUri" value="https://apihipaa.cloud.coveo.com/push" />
     <setting name="Coveo.Cloud.PlatformEndpointUri" value="https://platformhipaa.cloud.coveo.com" />
     <setting name="Coveo.Cloud.UsageAnalyticsEndpointUri" value="https://usageanalyticshipaa.cloud.coveo.com" />
   </settings>
 </sitecore>
</configuration>

  5. If you had already activated Coveo for Sitecore, reinstall the Coveo for Sitecore package you were using. After installation, the Coveo for Sitecore Configuration dialog will be displayed.

  6. Follow the activation procedure to link your Sitecore instance to your HIPAA organization.

  7. (Optional) If this isn’t your first Coveo for Sitecore activation, integrate custom configurations from your <SITECORE_INSTANCE_ROOT>\App_Config\Include\Coveo backup folder into the new <SITECORE_INSTANCE_ROOT>\App_Config\Include\Coveo folder as follows:

    • Restore the old Coveo.SearchProvider.Fields.Custom.config file from your backup folder to overwrite the newly created one.

    • Merge custom configurations from your old Coveo.SearchProvider.Custom.config file into the newly created one.

Activation procedure

  1. In the Coveo for Sitecore Configuration dialog, click Activate Coveo for Sitecore Package.

    Post install steps | Coveo
    Important

    You can also reach the Coveo for Sitecore Activation page at https://<INSTANCE_HOSTNAME>/coveo/command-center/index.html, where <INSTANCE_HOSTNAME> is replaced with your Sitecore instance name.

  2. In the Coveo for Sitecore Activation page, click Log In.

    Command Center Activation | Coveo for Sitecore 5

  3. Follow the instructions shown on screen to log in to Coveo using your preferred identity provider.

    If you already have access to one or several Coveo organizations, a screen with the Select your organization section similar to the following will appear:

    Activating Existing Organization | Coveo for Sitecore 5

    If you don’t have access to a Coveo organization, a screen with the Select your organization section similar to the following will appear:

    Activating New Organization | Coveo for Sitecore 5

  4. Select or create your Coveo organization.

    • To select an existing organization

      1. In the Select your organization section, select the Existing tab.

      2. Select the desired organization from the dropdown menu.

        Note

        You can only link to an organization in which you’re a member of the Administrators group.

        Coveo for Sitecore 5.0.788.5

        The flag next to the organization name indicates the region the organization data is hosted in. The flag tooltip provides further details on the organization data residency location.

        Image of Select Organization dropdown menu with region flags | Coveo for Sitecore 5

    • To create a new organization

      1. In the Select your organization section, select the Create New tab.

        Creating a new organization | Coveo for Sitecore 5

      2. In the Organization Name field, type the name you want for your Coveo organization.

        Notes

        • While you can always change your organization display name later in the Coveo Administration Console (platform-ca | platform-eu | platform-au) under Settings > Organization > Profile, be aware that the original name value you specify when creating an organization will forever be part of the unique and permanent ID of that organization.

        • Organizations created through Coveo for Sitecore are hosted in the us-east-1 region.

      3. Select the Organization Type that matches your needs (see Entitlement comparison (Coveo for Sitecore)).

        Tip
        Leading practice

        Coveo for Sitecore 5.0.858.1

        For a local development environment, select the Test organization organization type.

      4. Coveo for Sitecore 5.0.858.1

        In the Organization Region dropdown menu, select the data residency region that best suits your needs.

  5. Coveo for Sitecore 5.0.858.1

    In the Index Sitecore Content section, use the Index Sitecore content checkbox to specify whether you want to index your Sitecore instance content.

    Index Sitecore content option | Coveo for Sitecore 5
    Important

    The Index Sitecore content option is associated with the disableSourceCreation element in the Coveo.SearchProvider.Custom.config file. If you unselect Index Sitecore content now and later decide to index Sitecore content, you’ll need to do the following in the Coveo.SearchProvider.Custom.config file:

    • Set the value of the disableSourceCreation element to false.

    • Set the Sitecore credential sitecoreUsername (that is, domain\username), and sitecorePassword element values.

  6. If you selected Index Sitecore content, in the Configure options section, specify your Sitecore instance indexing-related configurations.

    Configure Options panel | Coveo for Sitecore 5

    Further details for each option are provided below:

    • Index permissions: Lets you select whether to index Sitecore permissions on the documents. When permissions aren’t indexed, all indexed documents are available to anonymous users. When permissions are indexed, a security provider is created in Coveo to ensure user access to documents follows Sitecore permissions. If your site contains secure content, we recommend that you index the permissions.

    • Body indexing: Lets you select whether the rendered HTML should be indexed.

    • Farm configuration: Lets you specify a Farm name to set coherent names for your resources (that is, sources and security identity providers).

      Important

      By default, Coveo for Sitecore sources are named Coveo_master_index - <FARM_NAME> and Coveo_web_index - <FARM_NAME> in your Coveo organization. As a result, if multiple Sitecore instances use the same farm name and are linked to the same Coveo organization, their items are indexed in the same sources.

      This is rarely useful in a development scenario, but a leading practice in a scaled production environment.

      Multiple developers shouldn’t link their instances to the same Coveo organization and use the same farm name. With this setup, a rebuild in one Sitecore instance deletes all items in your Coveo for Sitecore sources that come from the other linked Sitecore instances. Instead, each developer should use their own trial or test Coveo organization.

      In a scaled production environment, where multiple Content Management (CM) servers share the same databases, using the same farm name across all CMs and CDs is ideal. This ensures all CMs and CDs pull results from the same public website-related Coveo source (for example, a Coveo_pub_index - <FARM_NAME> source).

    • Sitecore credentials: Lets you specify the Sitecore account (domain\username) responsible for crawling the items and expanding permissions (see Sitecore credential usage).

      Tip
      Leading practice

      Create a dedicated Sitecore admin user for Coveo and use it in the activation steps. Assigning a dedicated user to Coveo for Sitecore will prevent lock-down issues.
      Notes

      • Coveo for Sitecore 5.0.362.4

        If you don’t specify a domain in the User name field, Coveo for Sitecore assumes the user is a member of the sitecore domain.

      • The password entered on this screen is encrypted and saved in the Coveo.SearchProvider.Custom.config.example file.

        Obsolete

        An encryption key is automatically created in the core database of your Sitecore instance.

        Coveo for Sitecore 5.0.387.10

        An encryption key is automatically created in the core database (for Sitecore versions up to 9.0 inclusively) or the web database (for Sitecore versions 9.1 onwards) of your Sitecore instance.

  7. Click Activate.

    Allow 15 to 30 minutes for your Coveo organization to be provisioned.

    Note

    At activation, the .config.example files below are renamed.

    • Coveo.CloudPlatformClient.Custom.config.example to Coveo.CloudPlatformClient.Custom.config

    • Coveo.SearchProvider.config.example to Coveo.SearchProvider.config

    • Coveo.SearchProvider.Custom.config.example to Coveo.SearchProvider.Custom.config

    • Coveo.SearchProvider.Rest.config.example to Coveo.SearchProvider.Rest.config

    • Coveo.SearchProvider.Rest.Custom.config.example to Coveo.SearchProvider.Rest.Custom.config

    • Coveo.UI.Controls.config.example to Coveo.UI.Controls.config

    • Coveo.UI.Components.ExperienceEditor.config.example to Coveo.UI.Components.ExperienceEditor.config

    These configuration files are located under <SITECORE_INSTANCE_ROOT>\App_Config\Modules\Coveo, except the *.Custom.config files which are located under <SITECORE_INSTANCE_ROOT>\App_Config\Include\Coveo.
    Note

    When a Coveo trial organization has been idle for some time, it’s paused automatically. If you have selected an existing organization that has been idle for a while, the following dialog box will be displayed:

    Cloud org paused | Coveo for Sitecore 5

    You can click Resume in the dialog box to resume using your organization.

    You can also reactivate your organization through the Coveo Administration Console (platform-ca | platform-eu | platform-au), in the notification center.

  8. Depending on your Sitecore revision, there may be some lines that you want to uncomment in the Coveo.SearchProvider.Custom.config file. Scan the file for any relevant section. For example, you may want to uncomment the <field fieldName="culture"> element.

    Important

    It’s important that you only modify the .Custom.config files. Modifying the .config files may lead to unexpected bugs during updates.

  9. Changes to your Web.config file are required to ensure that requests targeting the REST endpoint can handle special characters.

  10. Restart the Sitecore client.

    Install a package | Coveo for Sitecore 5

  11. If you’re using the web database, publish the master database, as items created by Coveo for Sitecore need to be replicated to the web database as well.

Important

Sitecore on Azure

Azure’s Web Application Firewall (WAF) may block Coveo query network calls that trigger OWASP rules. You might need to disable or customize Azure WAF rules to allow Coveo for Sitecore network calls (see Azure Web Application Firewall triggered rules block Coveo for Sitecore’s communication on Content Delivery servers).

What’s next?

When installing Coveo for Sitecore in a Sitecore configuration with several content management (CM) and content delivery (CD) hosts, see the scaling guide.

Otherwise you can return to the deployment guide.