Record models
The cartridge can generate three types of , depending on your record model preference:- Variation product records: create one record per product variant (default), with all properties at the root level of the Algolia record.
- Base product records: create one record per base product, containing all the variants in a
variantsarray. Simple products will also have avariantsarray for consistency. - Attribute-sliced records use a similar structure to Base product records but group variants by a shared attribute. For example, if the grouping attribute is
color, a product with multiple colors and sizes will generate one record per color. Each record includes all size variations for that color: one for red, one for blue, and so on.
To use the Attribute-sliced record model,
you must configure a grouping attribute such as
color.The Attribute-sliced record model is conceptually similar to Salesforce B2C Commerce’s variation group and slicing features.
However, you don’t need to create variation groups or slicing rules to use this feature.
If the base product has the configured variation attribute value,
Algolia splits it into multiple records.
Variation product record example
JSON
Base product record example
JSON
Simple products also include a
variants array for compatibility and consistency with the Base product record model.
This array contains the same properties as in base products,
such as in_stock, price, and url.image_groups aren’t stored in each variant.
For a given color, all size variations have the same image_groups.
Instead of duplicating image_groups in all variants, only one is stored for each color: in the colorVariations attribute.
The Algolia integration for Salesforce B2C Commerce uses a variant’s color information to determine which image to display.
Attribute-sliced record example
The Attribute-sliced record model is similar to the Base product record model, but base products which have the variation attribute configured in the site preferences are split into multiple records. Thevariants array contains all the non-common attributes of the variants that share the same variation attribute value (for example “color” of “red”).
Here is an example of such a record grouped by the color variation attribute:
JSON
Base products without a configured variation attribute in the Grouping attribute for the Attribute-sliced record model site preference use the same record format
but aren’t split into multiple records.Simple products also have a
variants array to ensure compatibility with the Attribute-sliced record model.Example
A site might have the following configurations:- hostname:
example.com - site-id:
clothing - Two locales:
en_US,fr_FR - Two currencies:
USD,EUR - Five additional product attributes:
short_description,long_description,brand,color,size
example-com__clothing__products__en_USexample-com__clothing__products__fr_FRexample-com__clothing__categories__en_USexample-com__clothing__categories__fr_FR
The prefix
${hostname}__${site_id} prevents accidental name collisions between your environments.
It makes using a single Algolia with multiple sandboxes or sites completely safe.
You can always change the prefix with the Algolia_IndexPrefix custom site preference.JSON
Configure product record 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.-
Go to Merchant Tools > Algolia > Algolia
-
Set up your Additional Product Attributes:
Base attributes (non-configurable)
The base set of attributes is always included in product indexing, except when using theattributeListOverride job step parameter, which overrides both the base attributes and any additional product attributes configured for that job.
| Attribute | Description |
|---|---|
name | Name of the product |
__primary_category | A hierarchy of the primary category. Used to create a hierarchicalMenu. |
categoryPageId | Array of category IDs assigned to the product. Used to create category pages |
url | URL of the product’s product detail page (PDP) |
image_groups | Array of product image URLs |
in_stock | true if the number of products available is greater than or equal to In-Stock Threshold you’ve set, false otherwise |
price | Product price |
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).
| Attribute | Description |
|---|---|
EAN | European Article Number of the product |
UPC | Universal Product Code of the product |
brand | Brand of the product. |
bundle | Whether this product instance is a product bundle |
bundled | Whether this product instance is bundled within at least one product bundle |
bundledProducts | Collection containing all products that participate in the product bundle |
color | Product color |
colorVariations | Array with an entry for each color variation. Each entry contains the image_groups of the variation, the variationUrl, and the variation color |
long_description | Full description of product |
lsImage | Expose the first product image at the root of the Algolia record. Used by the Looking Similar widget |
manufacturerName | Name of the product manufacturer |
manufacturerSKU | Value of the manufacturer’s stock keeping unit |
master | Whether this product instance is a product master |
masterID | ID of the master product |
newArrival | Whether this product is part of the newarrivals category |
online | Online status of the product. This is determined based on the product’s online status flag, and the onlineFrom and onlineTo dates |
optionProduct | Whether the product has options |
pageDescription | Product page description in the default locale |
pageKeywords | Product page keywords in the default locale |
pageTitle | Product page title in the default locale |
productSetProduct | Whether this product is part of any product set |
productSet | Whether the instance represents a product set |
promotionalPrice | Product’s lowest promotional price, from the currently active promotions. |
promotions | Array of promotions associated with the product. |
refinementColor | Search refinement bucket of the color. |
searchable | Whether the product is searchable |
size | Product size |
short_description | Short description of the product |
unit | Sales unit of the product |
variant | Whether this product instance belongs to a product master |
Flexible attribute indexing based on default behavior
From version 24.5.0, the Algolia cartridge supports indexing any product attribute, even if they aren’t explicitly listed as configurable attributes. This feature simplifies the process of indexing custom or specific attributes, allowing for more flexible and comprehensive product data in your Algolia index without requiring extensive configuration. For attributes that aren’t explicitly listed, the cartridge uses the following default indexing configuration:JavaScript
- Aren’t localized
- Are indexed in the
variantsarray (for the Base product and Attribute-sliced record models) - Use the default Salesforce B2C Commerce attribute name (with dot notation)
Nested attributes
Nested attributes are grouped under their parent object in the Algolia record. For example, if you want to indexactiveData.impressionsDay and activeData.revenueDay, they will be indexed in Algolia as:
JSON
Usage
To use this feature:- Add the corresponding Salesforce B2C attribute names (including nested attributes) to the Additional Product Attributes list in the Algolia Business Manager module Custom Preferences. Refer to custom attributes as
custom.<attribute_name>. - Apply the Custom Preference changes and run a full re-index.
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 aproductAttributesConfig.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:
| Property Name | Type | Description |
|---|---|---|
attribute | string or function | The attribute declaration. It can be: - The full path to the SFCC Product attribute name, separated by dots. - A function that takes the current product as parameter and returns data to be indexed in the Algolia record. |
localized | boolean | (Optional, default: false) Should be true if the attribute is localized. |
variantAttribute | boolean | (Optional, default: false) Only used with the Base product and Attribute-sliced record models, to identify attributes indexed in the variants array. |
computedFromBaseProduct | boolean | (Optional, default: false) Only used with the Variation product record model, to identify attributes computed once from the base product, and indexed into each variant. |
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.
JavaScript
JavaScript
Post-processing customization
To customize your records just before sending them to Algolia, create aproductRecordCustomizer.js file in the int_algolia/cartridge/configuration/ directory.
This lets the cartridge post-process 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:
JavaScript
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.
AlgoliaProductPriceIndex_v2:priceAlgoliaProductInventoryIndex_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.
Index active data
IndexProductActiveData fields, such as orders, revenue, and conversion metrics,
to use them for custom ranking.
The cartridge supports these fields by default, without a productAttributesConfig.js override.
Index active data at the record root
To index recommendedProductActiveData fields at the record root, use the Active data for custom ranking site preference in Business Manager.
- Go to Merchant Tools > Algolia > Algolia.
- In Active data for custom ranking, select the fields to index:
ordersWeek,revenueWeek,conversionWeek,ordersMonth,revenueMonth, orconversionMonth. - Click Apply.
- To reindex your data, go to Administration > Operations > Jobs and run the
AlgoliaProductIndex_v2job.
- In the Base product and Attribute-sliced record models, these values come from the base product.
- In the Variation product record model, these values come from each variant.
ProductActiveData attributes.
To index a property that isn’t in the checkbox list, add its ID (without the activeData. prefix) to Additional Product Attributes:
Additional product attributes
Attribute-sliced records use base product active data
In the Attribute-sliced model, active data added with the bare field name, such asrevenueWeek, comes from the base product.
The cartridge creates one record for each variation value, such as one record for each color.
However, it doesn’t calculate active data for only the variants in that slice.
Each slice gets the same value, calculated across all variants of the base product.
For example, a red slice doesn’t get the revenueWeek value for only the red variants. It gets the base product’s revenueWeek value.
To index active data for each slice, compute the value with a custom function using the extension mechanism.
Index per-variant active data
To index active data for each variant in thevariants[] array of the Base product or Attribute-sliced record models, use a nested or flat approach.
They produce different shapes inside each variant.
Nested per-variant value
Add the dotted field name, such asactiveData.<id>, to Additional Product Attributes.
Additional product attributes
activeData.revenueWeek is indexed as variants[i].activeData.revenueWeek.
Flat per-variant value
Use the extension mechanism to publish active data fields under different Algolia attribute names. To move an active data field from the record root into each variant, add an entry with the same key as the handler and setvariantAttribute to true.
JavaScript
Additional product attributes
revenueWeek field at its root inside variants[], with the same value as variant.activeData.revenueWeek.
The override replaces the built-in placement: the value no longer appears at the master record root.
After saving the file, run the AlgoliaProductIndex_v2 job to apply the change.
The same pattern works for any ProductActiveData IDs, and for any handler in attributeConfig_v2.
Rename an active data field
Use the extension mechanism to publish active data fields under different Algolia attribute names.JavaScript
popularity, to Additional Product Attributes and run the AlgoliaProductIndex_v2 job.
Use a custom function
Use a custom function to group several fields under a common top-level attribute, such asrevenueData.
-
In the extension configuration file (
productAttributesConfig.js), add arevenueDatadeclaration with theattributeproperty being a function that returns the data to index.JavaScript -
In Business Manager, go to Merchant Tools > Algolia > Algolia. Find Additional Product Attributes and add
revenueData. -
To reindex your data, go to Administration > Operations > Jobs and run the
AlgoliaProductIndex_v2job.
Make active data attributes unretrievable
ApplyunretrievableAttributes to every product index the cartridge writes to.
The cartridge creates one product index per locale per site, named <hostname>__<siteID>__products__<locale>.
JavaScript
forwardToReplicas to true.
When you save Active data for custom ranking in Business Manager, the cartridge checks every existing product index and warns if any selected field is missing from unretrievableAttributes.
The cartridge skips indices that don’t exist yet, so run AlgoliaProductIndex_v2 first to create them, then save the preference again to clear the warning.
The cartridge doesn’t check replica indices.
Apply unretrievableAttributes to each replica directly, or set forwardToReplicas to true when applying settings on the primary index.