Integrations Hub/
Algolia Integration

Integrating with Algolia

You can integrate Elastic Path Commerce Cloud with Algolia quickly and easily in Commerce Manager.

Whenever you publish a catalog, the full catalog is synced to Algolia using an index name composed of the catalog name and the first part of the catalog ID. This is triggered using events delivered by a webhook.

  1. When a catalog is published, a catalog-release.updated event is triggered.

  2. Once a catalog-release.updated event is received by the webhook, the integration begins to execute.

  3. The integration performs the following:

    • Retrieves product and taxonomy data for the catalog.
    • Retrieves the mapping for Elastic Path Commerce Cloud fields to Algolia fields.
    • Builds or updates the Algolia index.

For more information, watch a video.

Configuring Algolia in Commerce Manager

Collecting Your Setup Information

Before you begin configuring your Algolia integration in Commerce Manager, you need to collect the necessary setup information from Algolia and Commerce Manager.

Collect the following information and make sure you have it available, for example, in a text file, before configuring your Algolia integration in Commerce Manager. If you leave the Algolia Integration page in Commerce Manager, the integration is not saved and you must remove the integration and create a new one.

Collecting Algolia Setup Information

You can find this information in the Settings, Teams and Access, API keys section on the Algolia Dashboard.

App IDYour Application ID for your Algolia account.
Admin API keyYour Admin API Key for your Algolia account.

Collecting Commerce Manager Setup Information

Collect the following Elastic Path Commerce Cloud API keys. You can find this information in System > Application Keys in Commerce Manager when logged in as a user with Seller Admin privileges.

Elastic Path Commerce Cloud API KeyDescription
API Base URLYour Elastic Path Commerce Cloud API Base URL.
Client IDYour Elastic Path Commerce Cloud Client ID.
Client SecretYour Elastic Path Commerce Cloud Client Secret.

When integrating with third-party providers, we recommend you use the closest region in the third-party service to reduce latency as much as possible. See Regions and URLs table.

Configuring the Integration

Now that you've collected the setup information, let's begin by configuring the integration.

  1. In Commerce Manager, go to SYSTEM > Integrations Hub.
  2. Under Search, click on the Algolia Full /Delta / Large Catalog integration.
  3. Review the Summary page and click Configure. The current version information is displayed.
  4. Click Next.
  5. Configure the following information and click Finish.
Configuration parameterValue
Algolia Configuration Data: algolia_app_idYour Application ID for your Algolia account.
Algolia Configuration Data: algolia_admin_api_keyYour Admin API Key for your Algolia account.
Elastic Path Commerce Cloud Configuration Data: Client IDYour Elastic Path Commerce Cloud API Client ID.
Elastic Path Commerce Cloud Configuration Data: Client SecretYour Elastic Path Commerce Cloud Client Secret.
Elastic Path Commerce Cloud Configuration Data: Token URLYour Elastic Path Commerce Cloud API Token URL. For example, (EU) or (US). See Regions and URLs.
epcc_base_urlYour Elastic Path Commerce Cloud API Base URL. For example, (EU) or (US).
webhook_keySend to create secret for EPCC Integration (Examples: Simple Phrase, UUID).
Post Processing Configuration Data (Optional): webhook_urlOptional post-processing URL that the release details are sent to upon completion of an integration attempt.
Post Processing Configuration Data (Optional): webhook_api_keyOptional post-processing API key for the above URL.
Integration Tuning Parameters: batch_sizeThe default page size when synchronizing. The default is 250.
Integration Tuning Parameters: concurrent threadsThe number of threads that process each batch. The default is 10.

We recommend that you do not change the default tuning parameters. Contact Customer Success for more information.

The integration starts an execution which:

  • Configures a webhook to listen to the catalog-release.updated event, named EPCC Algolia Integration.
  • Creates a flow for containing field mappings between Elastic Path Commerce Cloud and Algolia, called Algolia Mapping.

It is important that you don't delete the Algolia Mapping flow or the EPCC Algolia Integration webhook, or the integration ceases to work.

Now that you've configured the integration, let's learn how you use it.

Understanding Field Mappings Between Elastic Path Commerce Cloud and Algolia

To sync the catalog to Algolia, you create a map of the data to pass from Elastic Path Commerce Cloud to Algolia. The mapping consists of:

  • Source field.
  • Destination field.
  • Any flags to trigger optional functions.

The integration uses a flow to contain the fields that you want to use. The source of the Elastic Path Commerce Cloud data is the catalog delta file. Additionally, there are some special fields that perform additional transformation work. When the integration is initially configured, a default set of mapping fields are created, but you can change these depending on your requirements. See the table below.

The following table describes some example fields in Commerce Manager and their corresponding fields in Algolia.

Elastic Path Commerce Cloud FieldMaps to Algolia FieldFlags
taxonomyep_categories. This field is used to trigger the creation of a hierarchy in Algolia.

The following are special field names:

  • main_image triggers a lookup of the URL from the file associated to the main image relationship on the product.
  • taxonomy retrieves the hierarchy and builds a custom Algolia-friendly format.

Creating new field mappings

  1. In Commerce Manager, go to Flows > Algolia Mapping. (If you have just configured your integration, refresh Commerce Manager to pick up the newly-added flow from the integration.)
  2. Click New Entry.
  3. Create the field mappings you desire by supplying the source field and destination field.
  4. In Algolia, create the fields described above. Refer to the documentation provided with Algolia for more information.

Mapping flags

The following mapping flags are available.

  • includeHierarchy - Use this flag if you want the name of the hierarchy to be included in the bread_crumbs.
  • forceSaleFlag - By default, if a price is on sale, an on_sale flag is set to true in the price book. If you also want an on_sale flag at the root of the product, you can add this flag to the price mapping.
  • forceJSON - It is a boolean value that is used to determine whether the input value should be parsed as JSON or not. This is useful if you want to treat an Elastic Path field as an embedded structure and not as a string.
  • convertDateToTS - A boolean value used to determine whether the input value is parsed as a date. The date is converted into a number that represents a UNIX timestamp.

Managing the Integration

Once the integration is configured and you have the mappings you want, the catalog is synced with Algolia with every new publish of your catalogs.

Partial updates

If a catalog has already been published and changes are made to the catalog and the catalog is published again, this results in a partial catalog update. In other words, only the products that have been created, updated or removed from the previous catalog release are updated. These are made directly to the live index in Algolia.

Full updates

A full catalog update can be triggered in the following scenarios.

  1. The first time a catalog is published. The delta file is then used to create a temporary index. The settings, rules, and so on, from the live version are then copied onto the temporary index. Once the index is completely loaded, the temporary index is moved to the live index.
  2. You can trigger a full catalog update by setting export_full_delta to true when publishing a catalog. Here's an sample request:
curl --location -g '{{pcmUrl}}/catalogs/{{catalogId}}/releases' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'x-moltin-auth-store: {{storeID}}' \
--data '{
    "export_full_delta" : true

Naming catalogs and indexes

Index names are created from the catalog name and a portion of the catalog id. This allows the integration to manage many catalogs at the same time. This dependency is important to consider when naming catalogs in Elastic Path Commerce Cloud and indexes in Algolia.

Was this helpful?