Upgrade to v23.5

Cartridge versions 23.4 and earlier (“Gen 1”) are deprecated and sunset since October 31, 2024. To take advantage of the improvements in the latest version, upgrade to the “Gen 2” cartridges (23.5 and later). Version 26.7.0 removes the v1 jobs and their code from the cartridge. If you upgrade from 23.4 or earlier to 26.7.0 or later, move to the v2 jobs as part of the upgrade. For more information, see the release notes.

Overview of the v2 jobs

For an overview of the v2 job system, see Indexing overview.

Before you begin

Delta exports

To take advantage of this new, more efficient job type for incremental product updates, raise a Salesforce support ticket to activate the feature. For more information, see Ongoing indexing.

Estimated upgrade duration

The duration of the upgrade depends on the extent of customization you have applied to the jobs. If you plan to fully transition to the v2 jobs without any extra customizations, the upgrade should take about 30 minutes to two hours to complete (excluding testing). If you have made customizations or extensions to the v1 jobs and want to apply them to the v2 jobs as well, the upgrade duration depends on the extent of these.

Before attempting any such customizations, consult your Solutions Engineer, Customer Success Manager/Engineer, or submit a Support ticket to discuss recommended integration approaches.

Comparison of the jobs

The old jobs (v1)

Relied on the old B2C job framework (no steptypes.json)
Were sequential (no parallelization)
Relied on intermediary XML files to store data temporarily
Relied on a middleware to split the data into multiple indices by locale
Delta calculation was slow with large datasets due to calculating the delta by comparing the current full catalog export to a previous one (snapshot) and writing the diff into a file
Couldn’t be used for multi-instance indexing (where part of the product data is sent from Staging, while another part from Production)
Use a less error-resilient and scalable end-to-end indexing approach and have limited monitoring and logging capabilities

List of v1 jobs

AlgoliaCategoriesIndex - for indexing the category tree
AlgoliaProductsIndex - for indexing product data - both full catalog indexing and product delta updates
AlgoliaProductsDeltaExport (v23.4.x only) - an earlier, sequential version of the v2 delta job
AlgoliaProductPricesExport (v23.4.x only) - an earlier, sequential version of the v2 price job
AlgoliaProductInventoryExport (v23.4.x only) - an earlier, sequential version of the v2 inventory job

The new jobs (v2)

Rely on the newer B2C job framework (steptypes.json)
Are chunk-based and parallelized (chunks are executed in parallel). Full (atomic) reindexing provides a zero-downtime full catalog reindexing option, useful for removing stale .
Don’t use intermediary XML files. Data is processed in chunks and sent immediately at the end of each chunk
Send data directly to Algolia
- Data is split into multiple indices by the B2C job internally
- There’s less possibility for error due to the end-to-end chain being shorter
Delta calculation is fast since it uses the platform’s built-in delta export mechanism
- Temporary data isn’t written to a file before sending
- B2C delta exports provide a fast and efficient way to determine which products have changed since the last export
Can be used for multi-instance indexing (part of the product data can be sent from staging, while another part, such as inventory or price data, from production)
- Partial updates allow for more frequent, lightweight updating of specific attributes rather than the entire record (for example price or inventory data only)
Text-based logs are more verbose, they cover more edge cases and error messages contain more information
Have a more extensive job reporting and monitoring system where reports are stored as custom objects instead of an XML file and are cleaned up automatically after a predetermined amount of time

List of v2 jobs

AlgoliaCategoryIndex_v2 - for indexing the category tree
AlgoliaProductIndex_v2 - for full catalog indexing (incl. full reindexing)
AlgoliaProductDeltaIndex_v2 - for product delta updates
AlgoliaProductInventoryIndex_v2 - for indexing inventory data only
AlgoliaProductPriceIndex_v2 - for indexing price data only

For more details about v2 jobs, see the Indexing overview page.

Changes from previous versions

The list of base (non-configurable) attributes has changed, as well as the recommended starting list of Additional Product Attributes (configurable), which was previously called “Custom Fields”.

Base attributes

Changed from: id, primary_category_id, in_stock, price, categories
To: name, primary_category_id, in_stock, price, categories, image_groups, url

id is always sent (as the objectID field).

Additional product attributes recommended starting list

Changed from: name, short_description, long_description, price, brand, color, size, image_groups
To: short_description, long_description

You can extend this list with any other attributes you like to index, see Indexing attributes.

Items added or updated in the latest version

Jobs

AlgoliaCategoryIndex_v2
AlgoliaProductIndex_v2
AlgoliaProductDeltaIndex_v2
AlgoliaProductInventoryIndex_v2
AlgoliaProductPriceIndex_v2

Services

algolia.http.search.write - used by the v2 jobs

Site preferences

Algolia_AdditionalAttributes (from Algolia_CustomFields)

Items to remove after the upgrade

You can remove these items after you move to the v2 jobs. Importing services.xml from version 26.7.0 or later deletes the algolia.http.export service. Remove the other items by hand. For more information, see Remove the v1 jobs and their configuration.

Jobs

AlgoliaCategoriesIndex
AlgoliaProductsIndex
AlgoliaProductsDeltaExport
AlgoliaProductPricesExport
AlgoliaProductInventoryExport

Services

algolia.http.api (versions before 23.3.0) and related credentials and profile
algolia.http.export (versions 23.3.0 and later) and related credentials and profile
algolia.http.ingestion (versions 23.3.0 to 23.4.1) and related credentials and profile. Indexing with the Ingestion API doesn’t use this service.

Site preferences

Algolia_HostBase
Algolia_OCAPIClientID
Algolia_OCAPIClientPassword
Algolia_CustomFields (renamed to Algolia_AdditionalAttributes). You can remove Algolia_CustomFields if you’re not planning on using the v1 jobs in the future

Migration steps

Take care when upgrading customized files so that you don’t overwrite any customizations. For any customizations and extensions you’ve made to the cartridge, consider whether they’re still applicable as they may now be supported by the cartridge natively:

Partial updates (including for price and inventory data updates)
Multi-instance indexing
Facet bucketing
Server-side rendering of category landing page and search results (first page only, can be extended) for improved SEO
Starting with v24.3.0, the cartridge lets you customize advanced product attributes without having to modify the jobs’ code. Use it for all customizations.
Configurable record structure (starting with v.24.2.0)

See the What’s Changed notes on GitHub for an up-to-date list of all new capabilities. For more details, contact your Solutions Engineer, Customer Success Manager/Engineer, or submit a Support ticket.

Upgrading the cartridge doesn’t remove the v1 job definitions from your instance, and new installations don’t create them. From version 26.7.0, the cartridge doesn’t include the v1 job code, so v1 jobs left on an instance end in error. To remove them, see Remove the v1 jobs and their configuration.

v2 jobs have new names and a “_v2” suffix to differentiate them from the old job system, so they won’t overwrite any existing jobs.

Update the code

Download the latest cartridge version from Algolia B2C Cartridge GitHub repository.
Remove the previous cartridge version from your repository and add the new version, so that no outdated files remain. If you customized the v1 jobs, move your customizations to the v2 jobs. For the main logic changes, see Code changes highlights.

Code changes highlights

To help you migrate your customizations, this section highlights the main logic changes between the two cartridges.

The v2 jobs use different files from the v1 jobs:

algoliaLocalizedProduct.js replaces algoliaProduct.js (the data model)
algoliaProductIndex.js replaces productsIndexJob.js (the main job logic)

Version 26.7.0 removes the v1 files. The links in this section point to version 24.1.0, which includes both.

Generated data

Before version 23.5.x (v1), jobs built the records data with the AlgoliaProduct model (algoliaProduct.js). For each product, this model generates a JSON object, where each attribute is an object containing values for each enabled site locale. The final object looks like this:

JSON

{
  "name": {
    "en_US": "Draped Cowl Neck",
    "fr_FR": "Top à col drapé"
  },
  "color": {
    "en_US": "Ivory"
    "fr_FR": "Ivoire",
  },
  "price": {
    "USD": 61.99,
    "EUR": 44.63
  },
  "in_stock": true,
  "primary_category_id": "womens-clothing-tops",
  "categories": [
    [
      {
        "id": "womens-clothing-tops",
        "name": {
          "en_US": "Tops",
          "fr_FR": "Tops"
        }
      },
      {
        "id": "womens-clothing",
        "name": {
          "en_US": "Clothing",
          "fr_FR": "Vêtements"
        }
      },
      {
        "id": "womens",
        "name": {
          "en_US": "Womens",
          "fr_FR": "Femme"
        }
      }
    ]
  ]
}

In version 23.5.x and greater (v2), the cartridge directly builds the final Algolia records. For each product, the job generates one separate AlgoliaLocalizedProduct object (algoliaLocalizedProduct.js) for each desired locale. A typical record from this model looks like this:

JSON

{
  "name": "Draped Cowl Neck",
  "color": "Ivory",
  "price": {
    "USD": 61.99,
    "EUR": 44.63
  },
  "in_stock": true,
  "primary_category_id": "womens-clothing-tops",
  "categories": [
    [
      {
        "id": "womens-clothing-tops",
        "name": "Tops"
      },
      {
        "id": "womens-clothing",
        "name": "Clothing"
      },
      {
        "id": "womens",
        "name": "Womens"
      }
    ]
  ]
}

Jobs logic

The v1 job code:

Generates models with the getNextProductModel() helper
Wraps the models into an UpdateProductModel object. This object is sent to the indexing middleware.
The middleware splits the provided object to create one final record per locale. This is then sent to the corresponding Algolia index.

In v2, the cartridge doesn’t use the indexing middleware. It’s the job itself that loops on enabled locales and directly creates the final Algolia records. You can see this logic in the algoliaProductIndex.js file. Thus, one of the main differences between v1 and v2 is the location of the loop handling the locales: For v1 jobs, the loop is inside the AlgoliaProduct model, when fetching a product attribute value:

JavaScript

  // algoliaProduct.js
  value = {};
  for (var l = 0; l < siteLocalesSize; l += 1) {
      var localeName = siteLocales[l];
      request.setLocale(localeName);
      value[localeName] = aggregatedValueHandlers[attributeName]
          ? aggregatedValueHandlers[attributeName](product)
          : ObjectHelper.getAttributeValue(product, config.attribute);
  }

For v2 jobs, the local handling loop is processed before generating the record:

JavaScript

  // algoliaProductIndex.js
  for (var l = 0; l < siteLocales.size(); ++l) {
      var locale = siteLocales[l];
      var indexName = algoliaData.calculateIndexName('products', locale);
      var localizedProduct = new AlgoliaLocalizedProduct({ product: product, locale: locale, attributeList: attributesToSend });
      // ...
  }

Update metadata, jobs, and services

Import metadata files from the metadata/algolia/meta folder in the repository: system-objecttype-extensions.xml and custom-objecttype-definitions.xml
Import job definitions: metadata/algolia/jobs.xml
Import services: metadata/algolia/services.xml

For detailed instructions on importing files in Business Manager, see the Set up the Algolia cartridge page.

Business Manager configuration updates

Go to the Merchant Tools > Algolia > Algolia in Business Manager
Fill in your Additional Product Attributes according to your use case.
You can start with short_description, long_description.

Job configuration

Go to Administration > Operations > Jobs in Business Manager
For each of the v2 jobs, set the execution site by clicking on the job, then go to Job Steps. Click Scope and then select the sites you want to run the jobs for.
Click AlgoliaProductDeltaIndex_v2, click Job Steps, then *Job Parameters
Click the catalogIDs parameter and add the catalog IDs assigned to your sites.

For more information about setting up the jobs, see Start indexing your data.

Remove the v1 jobs and their configuration

The v1 jobs stopped working on October 31, 2024, when the Stream middleware at https://sfcc-stream.algolia.com was sunset. From version 26.7.0, the cartridge doesn’t include them. After you move to the v2 jobs, remove the v1 jobs and their configuration from your instance.

Jobs

Go to Administration > Operations > Jobs and remove the v1 jobs:

AlgoliaCategoriesIndex
AlgoliaProductsIndex
AlgoliaProductsDeltaExport
AlgoliaProductPricesExport
AlgoliaProductInventoryExport

Services

Go to Administration > Operations > Services and remove these services with their credentials and profiles:

algolia.http.api
algolia.http.export. Importing services.xml from version 26.7.0 or later deletes it.
algolia.http.ingestion

Site preferences

Go to Administration > Site Development > System Object Types > SitePreferences > Attribute Definitions and filter for preferences starting with “Algolia_” by searching for “Algolia_*”. Remove the following site preferences:

Algolia_HostBase
Algolia_OCAPIClientID
Algolia_OCAPIClientPassword
Algolia_CustomFields (renamed to Algolia_AdditionalAttributes)

The v1 jobs sent the values of Algolia_OCAPIClientID and Algolia_OCAPIClientPassword, encrypted, to the Stream middleware. If that API client isn’t used for anything else, deactivate it in Account Manager.

Job files

The v1 jobs stored their reports and intermediate XML files in the Impex > src > Algolia folder. The v2 jobs don’t use this folder. To delete the files, go to Administration > Site Development > Development Setup > Folder Browser > Impex > src > Algolia. Version 26.7.0 removes the v1 Job Reports (Deprecated) section from the Algolia Business Manager module.

Confirm the success of the upgrade

Your , Search , and Admin API key should be configured already from your previous installation (go to the Algolia Business Manager module and set them up if not). After performing the preceding steps to upgrade to the v2 jobs, the Algolia v2 jobs appear in Business Manager under Administration > Operations > Jobs. Run all the jobs, one after the other, and verify whether they finish with an OK status. Go to your Algolia dashboard and confirm that your indices were updated.

​Overview of the v2 jobs

​Before you begin

​Delta exports

​Estimated upgrade duration

​Comparison of the jobs

​The old jobs (v1)

​List of v1 jobs

​The new jobs (v2)

​List of v2 jobs

​Changes from previous versions

​Base attributes

​Additional product attributes recommended starting list

​Items added or updated in the latest version

​Jobs

​Services

​Site preferences

​Items to remove after the upgrade

​Jobs

​Services

​Site preferences

​Migration steps

​Update the code

​Code changes highlights

Generated data

Jobs logic

​Update metadata, jobs, and services

​Business Manager configuration updates

​Job configuration

​Remove the v1 jobs and their configuration

​Jobs

​Services

​Site preferences

​Job files

​Confirm the success of the upgrade

Overview of the v2 jobs

Before you begin

Delta exports

Estimated upgrade duration

Comparison of the jobs

The old jobs (v1)

List of v1 jobs

The new jobs (v2)

List of v2 jobs

Changes from previous versions

Base attributes

Additional product attributes recommended starting list

Items added or updated in the latest version

Jobs

Services

Site preferences

Items to remove after the upgrade

Jobs

Services

Site preferences

Migration steps

Update the code

Code changes highlights

Update metadata, jobs, and services

Business Manager configuration updates

Job configuration

Remove the v1 jobs and their configuration

Jobs

Services

Site preferences

Job files

Confirm the success of the upgrade