Map commerce fields

This is for:

In this article

Prerequisites
The two layers of mapping
Map fields for a Catalog source
Map fields for other source types

Coveo for Commerce implementations require you to map the metadata in your index to specific commerce fields.

The process of mapping metadata to fields depends on the type of source you use to index your catalog data: the Catalog source or other eligible cloud sources. This article covers both scenarios.

The resource snapshots feature lets you copy configurations from one Coveo for Commerce organization to another, such as when you migrate from a sandbox to a production organization. It only copies the source configuration, not the source content.

Use this feature to reuse your catalog entities and their catalog configurations, your Catalog sources, and your fields and field mappings.

Prerequisites

Create the standard commerce fields.

When you Create a Catalog source in your Coveo organization, the standard commerce fields (such as ec_name, ec_description, and ec_price) are automatically generated and can’t be changed. With other source types, you must create these fields yourself.
Create the catalog structure fields.
Create your custom fields.

The two layers of mapping

There are two layers of mapping that must be done in your Coveo organization:

The catalog configuration mapping layer. This layer of mapping is critical for enabling Coveo Personalization-as-you-go (PAYG) and event tracking.
The source mapping layer. This layer of mapping enforces the Coveo Platform to properly fill the fields in your index with the metadata in your catalog data.

The following sections explain how to properly set up these two layers of mapping, depending on the type of source you use to index your catalog data:

Map fields for a Catalog source
Map fields for other source types

Map fields for a Catalog source

This section details the field mapping process when you use a Catalog source to index your catalog data.

It covers the two layers of mapping that you must complete:

Catalog configuration mapping
Source mapping

Catalog configuration mapping

When you create a catalog entity in your Coveo organization, you must define a catalog configuration. In this configuration, you must define the catalog configuration mappings for the standard commerce fields.

You define mappings at two different points in the catalog entity creation process:

When defining the catalog objects that compose your catalog entity (products, variants, and availabilities).
On the Standard fields tab of the catalog configuration.

Step 1: Catalog objects mapping

When defining the catalog objects that compose your catalog entity in the catalog configuration, you must select the metadata keys in your catalog data that correspond to the unique identifiers of your products, variants, and availabilities. For example, if your catalog data uses the product_id metadata key to uniquely identify your products, you must select this key when defining the Product catalog object.

If your catalog data contains variants and availabilities, you must also select the metadata keys that uniquely identify these catalog objects. For example, if your catalog data uses the variant_id and availability_id metadata keys to uniquely identify your variants and availabilities, you must select these keys when defining the Variant and Availability catalog objects.

Catalog objects mapping in catalog configuration | Coveo for Commerce

Step 2: Standard fields mapping

Still within the catalog configuration process, you must use the Standard fields section to define catalog configuration mappings for the standard commerce fields. This step is critical for:

Making sure that Coveo Personalization-as-you-go (PAYG) can build a product vector space that represents your content.
Tracking Coveo Analytics events using the Event Protocol. This ensures that commerce events are enriched with the required catalog data, such as ec_item_group_id, ec_category, and ec_brand.

For each applicable standard commerce field listed in the Standard fields section, specify the corresponding metadata key in your catalog data. For example, if your catalog data uses the price metadata key to store product prices, map price to the ec_price standard commerce field.

Standard fields mapping in catalog configuration | Coveo for Commerce

Source mapping

With a Catalog source, the standard commerce field mappings defined in the catalog configuration are automatically applied at the source level.

Don’t define source mappings for the standard commerce fields:

Any source mappings for the standard fields will be overwritten by the catalog configuration mappings.
source mappings for these fields can’t be used to drive Coveo Machine Learning (Coveo ML) data models.

Don’t create source mappings for the standard commerce fields when you use a Catalog source. However, you must create source mappings for the following fields:

Catalog structure fields
Custom fields
permanentid field
language field

Catalog structure fields mapping

To structure and configure your catalog entity, you must use a set of structure fields to set up the relationships between your items, their variants, and their availabilities.

Whether you need to create source mappings for the catalog structure fields depends on the nomenclature you used in your catalog data to define the metadata keys that correspond to these fields. If the metadata keys in your catalog data match the names of the catalog structure fields exactly, you don’t need to create source mappings for these fields. However, if the metadata keys in your catalog data differ from the names of the catalog structure fields, you must define source mappings for these fields.

For example, if the metadata key to uniquely identify a variant in your catalog data is variant_code, you must create a source mapping that maps the ec_variant_id field to the variant_code metadata key. However, if the metadata key in your catalog data is also named ec_variant_id, you don’t need to create a source mapping for this field.

Make sure that the metadata keys you map to the catalog structure fields correspond to the unique identifiers you selected when defining the Product, Variant, and Availability catalog objects in the catalog objects mapping step.

For example, if you selected the variant_code metadata key to uniquely identify your variants when defining the Variant catalog object in the catalog configuration, you must also map variant_code to the ec_variant_id catalog structure field.

Custom fields mapping

For any additional fields that you create in your Coveo organization, you must create mapping rules to map the metadata to these custom fields.

Example

You uploaded the following product data to your source:

{
  "documentId": "product://001-red",
  "FileExtension": ".html",
  "ec_name": "Coveo Soccer Shoes - Red",
  "model": "Authentic",
  "brand": "Coveo",
  "ec_description": "<p>The astonishing, the original, and always relevant Coveo style.</p>",
  "color": "Red",
  "ec_item_group_id": "001",
  "ec_product_id": "001-red",
  "ec_images": ["https://myimagegallery?productid"],
  "gender": "Men",
  "price": "30",
  "ec_category": "Soccer Shoes",
  "objecttype": "Product"
}

In your organization, you created the following fields to store additional metadata about your products:

product_color
product_gender
product_model

Therefore, you create mapping rules to map the color, gender, and model metadata to the product_color, product_gender, and product_model fields.

Map to `permanentid`

When using a Catalog source to index your catalog data, the Coveo Platform automatically creates a standard commerce field named ec_product_id to hold unique product identifiers. If you use ec_product_id as the name of the metadata key that uniquely identifies your products in your catalog data, it’s automatically mapped to the ec_product_id and permanentid fields in your Coveo organization.

However, you may prefer to use a different name for the metadata key that uniquely identifies the items in your source, in which case the mappings aren’t done automatically. This unique identifier can vary, depending on whether your items are products, variants, or availabilities.

In this case, you must manually map the metadata key that uniquely identifies the items in your source to the permanentid field.

The unique identifier that you map to the permanentid field must be the same as the one you selected when defining the Product catalog object in the catalog objects mapping step.

Not following this rule can cause Coveo for Commerce features that rely on consistent product identification to malfunction.

To map a unique identifier to the permanentid field

Identify the metadata key that uniquely identifies a product, variant, or availability in your catalog data.
Create a custom field in your Coveo organization that matches the name of the metadata key exactly.
Map the metadata key to this custom field.
Map the metadata key to the permanentid field.

Example

In your catalog data, the metadata key that uniquely identifies a product is product_code. You create a custom field in your Coveo organization named product_code and map your product_code metadata key to this field. You then map your product_code metadata key to the permanentid field.

Map to `language`

The Coveo Platform automatically detects languages when it indexes items. Although commerce sources only contain items in a single language, these items are often too short for automatic language detection. If an item doesn’t have a language, certain index ranking features, such as stemming and summarizing, aren’t supported.

To mitigate this, map the language metadata key in your catalog data to the default Coveo language field.

To map your language metadata key to the language field

Identify the metadata key associated with language in your catalog data.
Map this metadata key to the language field.