Map commerce fields

This is for:

Developer System Administrator

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

You also have to map certain metadata to two important default Coveo fields: permanentid and language.

Tip

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

Map standard commerce fields

The standard commerce field mappings are defined in the catalog configuration or in source mappings, depending on the source that you’re using.

The following table explains which type of mapping to use:

Mapping type Catalog source Other sources

Catalog configuration mappings

You define catalog configuration mappings for the standard commerce fields when you create your catalog entity.

You define catalog configuration mappings for the standard commerce fields when you create your catalog entity.

However, other sources don’t take the standard commerce field mappings from the catalog configuration.

Source mappings

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.

You must define source mappings for the standard commerce fields.

Catalog configuration mapping

When you create a catalog entity in your Coveo organization, use the Standard fields section to define catalog configuration mappings for the standard commerce fields. This step is critical for:

Tip

When structuring your product, variant, and availability data, use the same field names as the standard commerce fields (prefixed with ec_, such as ec_price).

If your catalog data uses different names from those the standard fields expect, such as price, map the standard commerce fields to your metadata in the catalog configuration.

If you use a Catalog source to index your catalog data, the standard field mappings defined in the catalog configuration will overwrite any source mappings for the standard commerce fields.

If you use any other source, the catalog configuration mappings aren’t replicated at the source level. You’ll have to manually create source mappings for the standard commerce fields.

Note

Don’t forget to push your catalog data into the source whenever you apply changes to the Standard fields section.

Catalog configuration mapping example

You upload the following product data to your Catalog 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"
}

Some product data is stored with keys that match the standard commerce fields:

  • ec_name

  • ec_description

  • ec_item_group_id

  • ec_product_id

  • ec_images

  • ec_category

However, other data that must fill the standard commerce fields is stored with different keys, such as brand and price.

When you map the standard fields in your catalog configuration, you map the brand and price metadata to the ec_brand and ec_price standard fields.

Source mapping

Whether you use source mapping for the standard commerce fields depends on the type of source you use to index your product inventory:

Important

Avoid modifying the metadata of standard commerce fields using an indexing pipeline extension (IPE). This action can make the data unusable for internal systems, such as Coveo Personalization-as-you-go models.

With a Catalog source

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.

With a cloud source

Unlike Catalog sources, Database, GraphQL API, REST API, and SAP sources don’t take the standard commerce field mappings from the catalog configuration. You must define source mappings for the standard commerce fields, even though you already mapped the metadata to these fields in the catalog configuration.

The Manage source mappings article provides all the information you need to define the proper mapping rules.

Map catalog structure fields

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.

When structuring your product, variant, and availability data, you should use the recommended field names. For example, use ec_variant_id to uniquely identify variant items in your source. In this case, the ec_variant_id field is automatically created and mapped to the ec_variant_id metadata key.

However, your catalog data may use different metadata keys, such as variantid to store the unique identifiers of variants. In this case, you must create a mapping rule that maps the ec_variant_id field to the variantid metadata key.

Map to permanentid

If you use 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.

Alternatively, you may use one of the following sources instead of a Catalog source, in which case the standard commerce fields aren’t created automatically:

In both of these cases, you must manually map the metadata key that uniquely identifies the items in your source to the permanentid field.

To map a unique identifier to the permanentid field

  1. Identify the metadata key that uniquely identifies a product, variant, or availability in your catalog data.

  2. Create a custom field in your Coveo organization that matches the name of the metadata key exactly.

  3. Map the metadata key to this custom field.

  4. 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. However, even though 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

  1. Identify the metadata key associated with language in your catalog data.

  2. Map this metadata key to the language field.

Map additional fields

In addition to the standard commerce fields and catalog structure fields, you may want to map other metadata to fields that you created in your Coveo organization.

For example, it’s likely that you created fields to store additional metadata that are relevant to the products you’re selling, such as color, size, gender, or model.

In this case, you must create mapping rules to map the metadata to the fields that you created in your organization.

Example

You uploaded the following product data to your Catalog 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.