Indexing

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

2. Select Algolia in Custom Site Preferences Groups

3. Set up your custom fields:

Base set (non-configurable attributes)

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

List of configurable attributes

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

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
    }
}

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.

Some attributes are protected. You should avoid creating or modifying attributes with the same name.

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

Some attributes are protected. You should avoid creating or modifying attributes with the same name.

Protected attributes

While you can customize, add, or remove most attributes from your record, some attributes are used by Algolia to structure your indexes. For this reason, Algolia recommends avoiding adding, removing, or modifying them:

• id
• primary_category_id
• __primary_category
• categories
• in_stock
• variants
• _tags

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.