Integrations / Platforms / Salesforce Commerce Cloud B2C / Indexing

The Algolia Link Cartridge for Salesforce Commerce Cloud B2C is currently in beta.

The role of the int_algolia cartridge is to keep your site’s data in sync with Algolia.

What data does the cartridge send?

The cartridge monitors the following data:

  • products, restricted to the attributes listed in your Custom Preferences.
  • categories.
  • inventory data, which adds in_stock: true|false attribute to your products indices.
  • price books (including promotional prices), which adds price and promotionalPrice attributes for all your site’s currencies.

Example

A typical installation on a site featuring:

  • hostname: example.com
  • site-id: clothing
  • 2 locales: en_US, fr_FR
  • 2 currencies: USD, EUR
  • 7 custom fields: name,short_description, long_description, price, brand, color, size, image_groups

This setup will generate the following indices in Algolia:

  • example-com__clothing__products__en_US
  • example-com__clothing__products__fr-FR
  • example-com__clothing__categories__en_US
  • example-com__clothing__categories__fr-FR

We generate a separate product and category index for each locale to give you the most flexibility in terms of configuration. This setup allows you to have synonyms, Rules, and other locale-specific settings on your index without interfering with the settings for other locales.

The prefix ${hostname}__${site_id} prevents accidental name collisions between your environments. It makes using a single Algolia application with multiple sandboxes or sites completely safe.

A typical record in these indices has the following structure:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
// index: example-com__clothing__products__en_US

  // Base set (non-configurable attributes)
  // theses fields are always added to your product record
  {
    "objectID": "8987698M",
    "categories": [
        [
          { "id": "womens-tops-tshirts", "name": "T-Shirts" },
          { "id": "womens-tops", "name": "Tops" },
          { "id": "womens", "name": "Women" }       
        ]     
    ],
  "__primary_category": {
     "0": "Womens",
     "1": "Womens > Tops",
     "2": "Womens > Tops > T-shirts"
   },
  "in_stock": true,
  "price": {
    "USD": 12.99,
    "EUR": 11.99
  },
  // configurable attributes
  "name": "Red T-shirt from PopularBrand",
  "short_description": "Short description of this red t-shirt",
  "long_description": "A much longer description of this red t-shirt",
  "brand": "PopularBrand",
  "color": "Red",
  "size": "L",
  "image_groups": [ /* */ ]
}

How do I keep my data in sync?

To keep your Algolia indices in sync with your SFCC data, you have either:

  • run the AlgoliaProductsIndex and AlgoliaCategoriesIndex jobs every time you know your data has been updated.
  • run the AlgoliaProductsIndex and AlgoliaCategoriesIndex jobs on a regular schedule, for example every few hours.
  • add the AlgoliaProductsIndex and AlgoliaCategoriesIndex jobs at the end of your catalog import job, to trigger a reindex of your data after you import it.

Both jobs construct the data that needs to be sent to Algolia by creating a snapshot of the data and computing the difference with the current state of your index. Then, the job only sends the updates to make the indexing process as fast as possible.

You can force the jobs to ignore the previous snapshot, and therefore send the full catalog. You can do this by setting the clearAndRebuild parameter to true.

How do I customize the indexing?

Configure the indexing jobs

  1. In your SFCC administration panel, go to Administration → Operations → Jobs.
  2. In the Job Steps section, make sure you’ve set the correct site for the scope of the job.

    The scripts that indexes products are:

    • (Step 1) for computing the updates: int_algolia/cartridge/scripts/algolia/job/productsIndexJob.js
    • (Step 2) for sending the updates to Algolia: int_algolia/cartridge/scripts/algolia/job/sendProductsDelta.js

    The scripts that indexes categories are:

    • (Step 1) for computing the updates: int_algolia/cartridge/scripts/algolia/job/categoryIndexJob.js
    • (Step 2) for sending the updates to Algolia: int_algolia/cartridge/scripts/algolia/job/sendCategoriesDelta.js

    The function name to use is: execute

You can force the jobs to ignore the previous snapshot, and therefore send the full catalog. You can do this by setting the clearAndRebuild parameter to true.

Configure extra attributes

The attributes your products contains in Algolia consist of a set of base attributes, and the attributes that you configure. You can configure the product attributes to send to Algolia by adding them to the Custom Fields setting. You should do this before performing a complete (re)index of your data.

  1. Navigate to Merchant Tools → Site Preferences → Custom Preferences Configure Algolia Custom Preferences Group

  2. Select Algolia in Custom Site Preferences Groups

  3. Set up your custom fields: Configure Algolia Custom Fields

Base set (non-configurable attributes)

The base set of attributes is always included in product index regardless of custom configuration.

id Product ID.
primary_category_id Primary category ID.
price Product price.
in_stock true if the number of products available is above the threshold you’ve set, false otherwise.
categories Array of categories assigned to the Product, with all their parent categories.

List of configurable attributes

You can choose to send the following attributes to Algolia by defining them in your Custom Fields:

EAN The European Article Number of the product.
UPC The Universal Product Code of the product.
brand The brand of the product.
bundle Identifies if this product instance is a product bundle.
bundled Identifies if this product instance is bundled within at least one product bundle.
bundledProducts A collection containing all products that participate in the product bundle.
image_groups Array of product image links.
long_description Full description of product.
manufacturerName The name of the product manufacturer.
manufacturerSKU The value of the manufacturer’s stock keeping unit.
master Identifies if this product instance is a product master.
name Name of product.
online The online status of the product. We decide this based on the product’s online status flag, and the onlineFrom and onlineTo dates.
optionProduct Identifies if the product has options.
pageDescription Returns product’s page description in the default locale.
pageKeywords The product’s page keywords in the default locale.
pageTitle The product’s page title in the default locale.
productSetProduct true if this product is part of any product set, otherwise false.
productSet Returns true if the instance represents a product set, otherwise false;.
promotionalPrice Product promotional price( calculated as product level.
promotions available at the time of job run. Not taking into account customer group, geolocation and other storefront-related information.
searchable Identifies if the product is searchable.
short_description Short description of product.
unit The products sales unit.
url Storefront product page link.
variant Identifies if this product instance belongs to a product master.

Adding custom attributes

You can add or create custom attributes by overriding the int_algolia/cartridge/scripts/algolia/lib/algoliaProductConfig.js file, and updating the attributeConfig object in the following way:

1
2
3
4
5
6
7
{
    /* ... */ 
    "algolia_attribute_name": {
        "attribute": custom.screenSize,
        "localized": false
    }
}
Property Name Type Description
algolia_attribute_name string Product attribute name for export to Algolia index.
attribute string The full path to the SFCC Product attribute name separated by a dot.
localized boolean Should be true if the attribute is localized.

After adding the description of the custom attribute to the configuration file, you can add it to the Custom Fields property in Algolia Site preferences.

Using a custom function

For more complex attributes, you may need to implement some custom logic. You can do so by overriding the function located in the int_algolia/cartridge/scripts/algolia/customization/productModelCustomizer.js module to add, remove or customize attributes before we send them to Algolia.

Any additional attribute added to the Product Model must be added to the Custom Fields property in Algolia Site preferences

Rebuilding your indices

We recommend setting up a dedicated jobs to performing this task, so that you can easily perform a full reindex when you notice your indices are out of sync.

Rebuilding products indices

To fully rebuild your products indices:

  1. Go to Administration → Operations → Jobs
  2. Click on New Job, then head over Job Steps:
  3. Add the following job steps:

    Step 1:

    1. Select ExecuteScriptModule.
    2. Fill in the following information:
      • ID: calculateProductsDelta
      • ExecuteScriptModule.Module: int_algolia/cartridge/scripts/algolia/job/productsIndexJob.js
      • ExecuteScriptModule.FunctionName: execute
      • Custom Parameters:
        • ID: clearAndRebuild , Value: true

    Step 2:

    1. Select ExecuteScriptModule.
    2. Fill in the following information:

      • ID: sendProductsDelta
      • ExecuteScriptModule.Module: int_algolia/cartridge/scripts/algolia/job/sendProductsDelta.js
      • ExecuteScriptModule.FunctionName: execute
  4. Make sure you have selected the correct site scope.

Rebuilding categories indices

To fully rebuild your category indices:

  1. Go to Administration → Operations → Jobs
  2. Click on New Job, then head over Job Steps:
  3. Add the following job steps:

    Step 1:

    1. Select ExecuteScriptModule.
    2. Fill in the following information:
      • ID: calculateCategoriesDelta
      • ExecuteScriptModule.Module: int_algolia/cartridge/scripts/algolia/job/categoryIndexJob.js
      • ExecuteScriptModule.FunctionName: execute
      • Custom Parameters:
        • ID: clearAndRebuild , Value: true

    Step 2:

    1. Select ExecuteScriptModule.
    2. Fill in the following information:

      • ID: sendCategoriesDelta
      • ExecuteScriptModule.Module: int_algolia/cartridge/scripts/algolia/job/sendCategoriesDelta.js
      • ExecuteScriptModule.FunctionName: execute
  4. Make sure you have selected the correct site scope.

Did you find this page helpful?