Indexing attributes

The cartridge can index various product, price, inventory and categories data from Salesforce B2C Commerce environments.

Default records

The cartridge can generate two types of records, depending on your record model preference:

• Variation Product records: create one record per product variant (default).
• Base Product records: create one record per base product, containing all the variants in a variants attribute.

For more information about which model best suits your needs, see Ecommerce records.

Variant-level default model

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
33
34
35
36
37
38
{
  "name": "Apple iPod Classic",
  "primary_category_id": "electronics-digital-media-players",
  "categories": [
    [
      {
        "id": "electronics-digital-media-players",
        "name": "iPod & MP3 Players"
      },
      {
        "id": "electronics",
        "name": "Electronics"
      }
    ]
  ],
  "in_stock": true,
  "price": { "USD": 219.99 },
  "image_groups": [
    {
      "_type": "image_group",
      "images": [
        {
          "_type": "image",
          "alt": "Apple iPod Classic, Silver, large",
          "dis_base_link": "/images/large/ipod-classic-silver.jpg",
          "title": "Apple iPod Classic, Silver"
        }
      ],
      "view_type": "large"
    }
  ],
  "url": "/electronics/ipod%20%26%20mp3%20players/apple-ipod-classic-silver-120gM.html"
  "__primary_category": {
    "0": "Electronics",
    "1": "Electronics > iPod & MP3 Players"
  },
  "objectID": "apple-ipod-classic-silver-120gM"
}

Product-level default model

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
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
{
  "name": "Apple iPod Classic",
  "primary_category_id": "electronics-digital-media-players",
  "categories": [
    [
      {
        "id": "electronics-digital-media-players",
        "name": "iPod & MP3 Players"
      },
      {
        "id": "electronics",
        "name": "Electronics"
      }
    ]
  ],
  "__primary_category": {
    "0": "Electronics",
    "1": "Electronics > iPod & MP3 Players"
  },
  "defaultVariantID": "apple-ipod-classic-silver-120gM",
  "variants": [
    {
      "variantID": "apple-ipod-classic-silver-120gM",
      "in_stock": true,
      "price": { "USD": 219.99 },
      "color": "Silver",
      "url": "/electronics/ipod%20%26%20mp3%20players/apple-ipod-classic-silver-120gM.html"
    },
    {
      "variantID": "apple-ipod-classic-black-120gM",
      "in_stock": true,
      "price": { "USD": 199 },
      "color": "Black",
      "url": "/electronics/ipod%20%26%20mp3%20players/apple-ipod-classic-black-120gM.html"
    }
  ],
  "colorVariations": [
    {
      "image_groups": [
        {
          "_type": "image_group",
          "images": [
            {
              "_type": "image",
              "alt": "Apple iPod Classic, Silver, large",
              "dis_base_link": "/images/large/ipod-classic-silver.jpg",
              "title": "Apple iPod Classic, Silver"
            }
          ],
          "view_type": "large"
        }
      ],
      "variationURL": "/electronics/ipod%20%26%20mp3%20players/apple-ipod-classicM.html?dwvar_apple-ipod-classicM_color=Silver",
      "color": "Silver"
    },
    {
      "image_groups": [
        {
          "_type": "image_group",
          "images": [
            {
              "_type": "image",
              "alt": "Apple iPod Classic, Black, large",
              "dis_base_link": "/images/large/ipod-classic-black.jpg",
              "title": "Apple iPod Classic, Black"
            }
          ],
          "view_type": "large"
        }
      ],
      "variationURL": "/electronics/ipod%20%26%20mp3%20players/apple-ipod-classicM.html?dwvar_apple-ipod-classicM_color=Black",
      "color": "Black"
    }
  ],
  "in_stock": true,
  "objectID": "apple-ipod-classicM"
}

Example

A site might have the following configurations:

• hostname: example.com
• site-id: clothing
• 2 locales: en_US, fr_FR
• 2 currencies: USD, EUR
• 5 additional product attributes: short_description, long_description, brand, color, size

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

Algolia generates a separate product and category index for each locale to give you the most flexibility in terms of configuration. This setup lets 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. You can always change the prefix with the Algolia_IndexPrefix custom site preference.

A typical variant-level 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
33
// 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": [ /* */ ],
  "url": "/s/RefArch/womens/tops/tshirts/8987698M?lang=en_US"
}

Configure product records attributes

You can configure the list of attributes that are exported to your Algolia index. The list has a set of base attributes which you can extend to match your business needs. Configure the product attributes to send to Algolia by adding them to the Additional Product Attributes preference. You should do this before performing a complete (re)index of your data.

1. Go to Merchant Tools > Algolia > Algolia

   

2. Set up your Additional Product Attributes:

   

Base attributes (non-configurable)

The base set of attributes is always included in product indexing, except when using the attributeListOverride job step parameter, which overrides both the base attributes and any additional product attributes configured for that job.

Configurable attributes

You can choose to send additional Product record attributes such as the following to Algolia by defining them in Additional Product Attributes.

You should start with the following attributes: short_description, long_description, then expand the list according to your use case (for example brand, color, size).

New arrivals facet

To ensure the custom logic in the Algolia cartridge correctly displays the new arrivals facet:

1. Add the newArrivalsCategory attribute to the Additional Product Attributes list to send it to Algolia.
2. Declare newArrivalsCategory as an attribute for faceting in the Algolia dashboard.

Advanced attributes configuration

Extend attributes declarations

The cartridge has an extension mechanism that lets you add new attributes, modify existing ones, or remove base attributes.

Create a productAttributesConfig.js file in the int_algolia/cartridge/configuration/ directory. For an example, see this file in the cartridge code. This file must export a configuration object. The keys of this object are the name of the attributes in your Algolia records. Each key holds an object with the following properties:

The attribute property lets you declare attributes with their direct name (simple values like name, brand, etc.) or their “path”, for nested values with direct access. For example, you can access the revenueWeek attribute of a product’s activeData object by declaring activeData.revenueWeek.

Other values are more complex and must be computed. For that, the attribute property accepts a function to define how to export such complex attributes.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
/* productAttributesConfig.js */
module.exports = {
    /* ... */
    "algoliaAttributeName": {
        /* Access directly a product's property (or nested property) */
        "attribute": "activeData.revenueWeek",
        "localized": false,
    },
    "siblings": {
        /* Compute an array of variants IDs from the base product */
        "attribute": function(product) {
            const variantIds = [];
            const variantsIt = product.variants.iterator();
            while (variantsIt.hasNext()) {
                var variant = variantsIt.next();
                if (variant.getAvailabilityModel().isInStock()) {
                    variantIds.push(variant.ID);
                }
            }
            return variantIds;
        },
        "computedFromBaseProduct": true,
    }
}

A more complete example is available in the cartridge code.

1
2
3
module.exports = {
    "in_stock": {},
}

Post-processing customization

To customize your records just before sending them to Algolia, create a productRecordCustomizer.js file in the int_algolia/cartridge/configuration/ directory. This permits to do post-processing operations on the final records, after fetching all attributes. This file must export a function that takes as parameter the final Algolia record and does modifications on it:

1
2
3
4
5
6
/* productRecordCustomizer.js */
module.exports = function(productRecord) {
    if (productRecord.colorVariations) {
        productRecord['availableColors'] = productRecord.colorVariations.length;
    }
}

Configure extra attributes for AlgoliaProductPriceIndex_v2 and AlgoliaProductInventoryIndex_v2

To extend the list of attributes sent by these jobs, select the job you want to configure in BM, go to the Jobs Steps tab, select the job step and edit the attributeListOverride parameter. Additional attributes can increase the job’s total runtime depending on the complexity of retrieving the attribute:

• Nested attributes from B2C model classes take longer to retrieve than the product’s own properties
• Calculated values take longer to retrieve than static values.

By default, these jobs send the following attributes:

• AlgoliaProductPriceIndex_v2: price
• AlgoliaProductInventoryIndex_v2: in_stock

If you extend the list of exported attributes, make sure to add the same attributes to the Additional Product Attributes site preference in the Algolia BM module as well so that the product delta export job also includes those attributes and updates them during its run.