Use in commercetools

This is for:

Developer

If you’re using commercetools as your product information management (PIM) system, you can use commercetools as your main product content repository and index its content in Coveo to leverage Coveo’s product discovery capabilities.

You can then synchronize with changes in commercetools to maintain your Coveo index up-to-date with the latest product information.

This article guides you through the process of indexing and maintaining commercetools products in Coveo. More specifically, it covers the following steps:

  1. Create a Catalog source in Coveo

  2. Export products from commercetools

  3. Format exported products to Coveo standards

  4. Push products to Coveo using the Streaming API

  5. Create a catalog entity

  6. Listen for changes in commercetools

  7. Update the Coveo index with the latest product information

Note

This article serves as a high-level guide to help you get started with indexing commercetools products in Coveo. It links to other articles that provide detailed instructions on how to perform the tasks described in this article.

It assumes that you have a basic understanding of Coveo and commercetools, as well as the necessary permissions to perform the tasks described in this article.

Step 1: Create a Catalog source in Coveo

To index products from commercetools in Coveo, you need to create a Catalog source in your Coveo organization. This source will be used to store the product information that you’ll push from commercetools.

See Add a Catalog source for instructions on how to create a Catalog source using the Coveo Administration Console.

Step 2: Export products from commercetools

To index products from commercetools in Coveo, you need to export the product information from commercetools.

commercetools provides a tool named ImpEx that allows you to export products in either CSV, XLSX, or JSON format. You’ll later use this exported file to push the product content to your Catalog source using the Coveo Stream API.

For instructions on how to export products from commercetools, see the Exporting Products ImpEx tutorial in the commercetools documentation. This tutorial guides you through the process of exporting products in CSV format, as well as linking to the ImpEx tool to perform product exports.

Once you’ve exported the products from commercetools, you must ensure the formatting of the exported content matches Coveo’s product schema (see the next step).

Step 3: Format exported products to Coveo standards

Once you’ve exported the products from commercetools, you need to format the exported products to match Coveo’s product schema.

Coveo expects the product information to be in a specific format to be able to index it correctly. For example, the items to push to Coveo are expected to be either of the Product, Variant, or Availability object type.

For more information about the Coveo for Commerce object types, as well as information on how to structure them, see Catalog object types.

You’ll also have to configure commerce fields in your Coveo index to store the metadata of the products you want to index. See About Coveo commerce fields and About product identifiers for more information.

About Coveo commerce fields

Coveo for Commerce requires specific fields to be present in the product information to be able to index it correctly and leverage Coveo Personalization-as-you-go features.

Therefore, you need to ensure that the content you exported from commercetools contains the required metadata, and that your Coveo index contains the necessary fields to store this metadata.

See Commerce fields for details.

About product identifiers

Coveo requires that each item has a unique identifier to be able to index and update it correctly.

In commercetools, the product identifier is stored in the id field and is formatted as a 32-character UUID.

While you can index this value in Coveo, you must ensure that each product or variant you want to index in Coveo has a unique documentId and productId.

In Coveo:

  • The documentId is the unique identifier of the item in the Coveo index. It’s mandatory to perform updates on the item.

  • The ec_product_id is the unique identifier of a product in the Coveo index. Among other things, this value is used to train Coveo Machine Learning (Coveo ML) models, product reporting, and merchandising actions on specific products.

  • The ec_variant_id identifies sellable units of a product. For example, if a product has multiple variants, each variant has a unique ec_variant_id. If a product has no variants, the product will have an ec_product_id and ec_variant_id that are identical.

  • The ec_availability_id is the unique identifier of an availability in the Coveo index.

Supported data types

Metadata in commercetools can be formatted in various data types. While Coveo supports most of the data types supported by commercetools, some data types may require additional formatting to be indexed correctly in Coveo.

Therefore, you need to ensure that the data types in the exported content are compatible with Coveo’s data types.

The following table provides a mapping of commercetools supported data types to Coveo supported data types, as well as the required conversion:

commercetools supported data type Equivalent in Coveo Required conversion

Boolean

String

Convert the boolean field to a string field, which has a value of either true or false.

Enum

String, Int32, Int64, Decimal, or Date

Depending on the enum values, break them down into multiple fields of the appropriate data type.

Reference

String, Int32, Int64, Decimal, or Date

Depending on the reference values, choose the data type that best accommodates the reference type. For example, if the field of the reference data type contains a URL, you can convert it to a string field.

Step 4: Push products to Coveo using the Streaming API

Once you’ve formatted the exported content to match Coveo’s product schema, you can push the content to your Catalog source using the Coveo Stream API.

The Stream your catalog data to your source article provides detailed instructions on how to push content to a Coveo source using the Streaming API.

Step 5: Create a catalog entity

Once you’ve pushed the products to your Coveo Catalog source, you need to create a catalog entity to establish the relationships between products, variants, and availabilities. This also allows you to enable Coveo personalization-as-you-go-features.

The Commerce catalog entity article provides detailed instructions on how to create and manage a catalog entity.

Tip
Leading practice

Once you’ve pushed the products to your Coveo Catalog source and created a catalog entity, you can inspect your indexed content in the Coveo Administration Console to ensure that the products are correctly indexed and that the relationships between products, variants, and availabilities are correctly established.

The Content Browser (platform-ca | platform-eu | platform-au) let’s you visualize the content of your Coveo index and inspect the relationships between products, variants, and availabilities. See Inspect content and properties for instructions.

Step 6: Listen for changes in commercetools

Once you’ve indexed your commercetools content in Coveo, you’ll want to maintain your Coveo index up-to-date with the latest changes in commercetools.

To do so, you can listen for changes in commercetools and update your Coveo index accordingly. You’ll need to implement a mechanism that listens for changes in commercetools to be able to update your Coveo index with the latest information.

commercetools HTTP APIs offer a subscriptions and messages features. Depending on the specific field of a product being updated in commercetools, you may need to utilize either the changeSubscription or product messages method.

To integrate with commercetools and transmit events to the Catalog source in Coveo, you’ll require a middleware solution in place to receive events from commercetools and process the changes accordingly.

Step 7: Update the Coveo index with the latest product information

Once you’ve implemented a mechanism to listen to changes in commercetools, your mechanism will need to update your Coveo index with the latest product information.

To update your Coveo index with the latest product information, you can use the Coveo Stream API to push the updated content to your Coveo Catalog source.

The How to update your catalog article provides detailed instructions on how to format the content received from commercetools and update your Coveo index with the latest product information using the Coveo Stream API.

High-level overview

The following diagram provides a high-level overview of the process of indexing and maintaining commercetools products in Coveo:

High-level flow of indexing and maintaining commercetools products in Coveo | Coveo