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 can use these commerce fields to:

When you create a Catalog source in your Coveo organization, the standard commerce fields are automatically generated and can’t be changed. For example, the ec_name, ec_description, and ec_price fields are all automatically created. With other source types, you must create these fields yourself.

You’ll also need to create catalog structure and custom fields.

After the required fields have been created, you must map the metadata of the items in your source to these fields.

Tip

If you’re migrating configurations from a Coveo for Commerce organization to another (for example, from a sandbox to a production organization), you can use the resource snapshots feature to copy configurations from one organization to another.

You can use this feature to reuse your catalog entities and their catalog configurations, Catalog sources, and fields and field mappings. Note that only the source configuration is copied, not the source content.

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.

Standard commerce fields catalog 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.

Standard commerce 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.

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.

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.

Mapping to permanentid

When using one of the following sources, you must manually map the metadata that uniquely identifies the items in your source to the permanentid field:

The unique identifier varies depending on whether your item is a product, variant, or availability.

When using a Catalog source to index your catalog data, the Coveo Platform automatically creates a standard field named ec_product_id to hold the unique identifier of a product. If you use ec_product_id as the metadata key that uniquely identifies your products, the mapping to the permanentid field is done automatically.

However, if your product metadata uses a different key for your product’s unique identifier, or if you don’t use a Catalog source, you must manually map your unique product identifier to the permanentid field. Additionally, you must create a custom field that matches the name of your chosen metadata key exactly.

Example

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

To manually map a unique product identifier to the permanentid field:

  1. Identify the metadata key that uniquely identifies a product in your catalog data.

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

  3. Map the permanentid to the metadata key used to fill the custom field.

Additional fields mapping

In addition to the standard commerce fields, you may want to map other metadata to fields that you created in your 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. The Manage source mappings provides all the information you need to define the proper mappings rules for your Catalog source.

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.