Use the Coveo Cartridge for B2C Commerce in Eclipse IDE

This is for:

Developer System Administrator

This article explains how to use the Coveo Cartridge for B2C Commerce (Coveo Cartridge) in the Eclipse IDE to push data from a Salesforce Commerce Cloud instance to a Coveo organization.

The indexed data can be used in a Coveo-powered search interface implemented in your storefront.

Important

This article focuses on installing the Coveo Cartridge in the B2C Commerce Storefront Reference Architecture (SFRA) environment. However, it’s possible to use it in the SiteGenesis architecture.

Most of the steps are the same for SiteGenesis; those that are different are formatted as SiteGenesis only notes.

Prerequisites

Make sure that your configuration meets the following criteria:

  1. The required software is installed on your machine:

  2. You have:

Step 1: Install the Coveo Cartridge in UX Studio

  1. Open the UX Studio plugin in the Eclipse IDE.

  2. Navigate to File → Import → General → Existing Projects Into Workspace.

  3. To the right of Select root directory, click the Browse button. A modal window opens.

  4. Navigate to the folder where you downloaded the Coveo Cartridge, then to the cartridges folder.

  5. Select the cartridges folder.

  6. Click the Ok button. The modal window closes.

  7. In the Projects section, select the following projects:

    • bm_coveo

    • int_coveo

    • int_coveo_sfra

    • int_coveo_sfra_changes

      SiteGenesis only
      Details

      • bm_coveo

      • int_coveo

      • int_coveo_sg

      • int_coveo_sg_changes

        Eclips IDE - import the SiteGenesis cartridges into a workspace

  8. Click the Finish button to finish the import.

    Eclips IDE - import the SFRA cartridges into a workspace

  9. The Eclipse IDE will prompt you to connect the cartridges to your sandbox. Click the Yes button.

Step 2: Map the fields

To enforce proper indexing, you need to map the product attributes in your Salesforce catalog to the fields in your Coveo organization. To do the mapping, you need to create a mapping file and upload it to your Salesforce instance.

By default, the Coveo Cartridge uses mapping located at the end of the file int_coveo/cartridge/scripts/utils/coveoConstant.js:

// ...
exports.COVEO_FIELD_MAPPER = {
    primaryCategory: {
        custom: {
            sizeChartID: {
                fieldName: 'gender',
                fieldType: 'string'
            }
        }
    },
    name: { 1
        fieldName: 'ec_brand', 2
        fieldType: 'string'
    },
    custom: {
        color: {
            fieldName: 'ec_color',
            fieldType: 'string'
        }
    }
};
1 The SFCC attribute name.
2 The Coveo field ec_brand that’s mapped to the SFCC attribute name.

Update this mapping as required.

Step 3: Assign the cartridges to a site

  1. In the Business Manager, navigate to Administration → Sites → Manage Sites.

  2. Click the Manage the Business Manager site button.

  3. Switch to the Settings tab.

  4. In the Cartridges field, add the following values at the beginning:

    bm_coveo:int_coveo:

  5. Click the Apply button.

  6. Navigate to Administration → Sites → Manage Sites.

  7. Click the name of the required site.

  8. Switch to the Settings tab.

  9. In the Cartridges field, add the following values at the beginning:

    int_coveo_sfra_changes:int_coveo_sfra:int_coveo
    SiteGenesis only
    int_coveo_sg_changes:int_coveo_sg:int_coveo

  10. Click the Apply button.

  11. Navigate to Administration → Site Development → Code Deployment.

  12. Select the checkbox to the left of the code version that you want to activate.

  13. Click the Activate button to activate the code version.

Step 4: Configure indexing

  1. In the Business Manager, click the Select a Site drop-down menu.

  2. Click the name of the target site.

  3. Navigate to Merchant Tools → Site Preferences → Custom Preferences.

  4. In the ID column, click the Coveo Configs link.

  5. Fill in the fields as follows:

    Name Value

    Coveo Enabled

    Yes

    Coveo Search Enabled

    Yes

    Coveo Chunk Mode Enabled

    Coveo API Key

    The API key to index the Salesforce catalog and send its data to a source in your Coveo organization. This API key should have the following privileges:

    Service Privilege Access level

    Content

    Sources

    Edit all[1]

    Organization

    Organization

    View

    See Manage API keys and Manage privileges.

    Coveo Search API Key

    The API key to use on a Salesforce search page.

    This API key should have the following privileges:

    Service Privilege Access level

    Analytics

    Analytics data

    Push

    Search

    Execute queries

    Allowed

    See Use API key authentication with the Search API and Manage privileges.

    Coveo Organization Id

    The ID of your Coveo organization.

    Coveo Source ID

    The ID of a Catalog source in your Coveo organization.

    Coveo Atomic CSS URL

    Don’t fill in this value to use the default URL, https://static.cloud.coveo.com/atomic/v2/themes/coveo.css.

    Coveo Atomic JS URL

    Don’t fill in this value to use the default URL, https://static.cloud.coveo.com/atomic/v2/atomic.esm.js

    Coveo Catalog Last Sync

    The last date and time when the catalog data was indexed. Only the products added on or after this date will be indexed.

    Coveo Search Response Fields

    Add created search fields that you added in your project. For example, ec_rating, ec_color.

    Coveo Search Hub

    The name of the search hub that’s used for the search page.

1. You can also set the Custom access level. Once you set it, you’ll need to select the Edit access level for the targeted push source and the View access level for the other sources.

Step 5: Import the Coveo service, profile, and credentials

The Coveo Cartridge contains an archive with the metadata of the Coveo services, profiles, and credentials that you must use. To import the metadata archive, perform the following steps:

  1. In the Business Manager, navigate to Administration → Site Development → Site Import & Export.

  2. Make sure that the Local option is selected.

  3. Click the Choose File button.

  4. Navigate to the folder where you downloaded the Coveo Cartridge, then to the metadata folder and select the metadata.zip file.

  5. You’ll see a new entry in the table, instance/metadata.zip. Select this entry, and then click Import.

  6. Once the archive is imported, your sandbox will have new entries added in Services, Profiles, and Credentials sections.

    1. Navigate to Administration → Operations → Services and switch to the Services tab. Check that the int.coveo.http.api service is present in the list of services. You don’t need to change the service’s parameters, but make sure they’re as follows:

      A Coveo service added to the Salesforce sandbox

    2. Switch to the Profiles tab. Check that the int.coveo.api.profile entry is present in the list of profiles. You don’t need to change the profile’s parameters, but make sure they’re as follows:

      A Coveo profile added to the Salesforce sandbox

    3. Switch to the Credentials tab. Check that the int.coveo.api.cred entry is present in the list of credentials. Click the int.coveo.api.cred link to open the credential’s details. You don’t need to change the parameters, but make sure they’re as follows:

      The Coveo credentials added to the Salesforce sandbox

      The User and Password fields are default sandbox fields and not used by the Coveo Cartridge, so their values don’t matter.

Step 6: Push the catalog to Coveo

Once the metadata.zip archive is imported, there are two jobs available in your Salesforce sandbox:

  • ProductsFeedExportFull: the job to push the entire catalog to Coveo. It suits the first time when you need to index your catalog.

  • ProductsFeedExportDelta: the job to push only the products that were updated or added after the date set in the Coveo Catalog Last Sync field. See Configure indexing.

To make the jobs operational, do the following:

  1. Navigate to Administration → Operations → Jobs.

  2. Click the required job to open its settings.

  3. Switch to the Job Steps tab.

  4. Next to the Scope label, click X Sites Assigned.

  5. In the modal window that appears, select the checkbox to the left of the required site.

    Optional: you may select or clear the checkboxes for other available sites, if required.

  6. Click the Assign button.

  7. While at the job’s settings, you can:

    • Run the job manually by clicking Run Now.

    • Schedule the job to run automatically in the Schedule and History tab.