Map commerce fields

This is for:

Developer System Administrator

Coveo for Commerce implementations require the use and creation of specific index fields.

The Commerce fields article provides an exhaustive list of the standard fields that must be used, along with information on how to leverage catalog structure fields and create your own custom fields.

These commerce fields are essential to the proper functioning of the Coveo for Commerce solution. They let you:

Standard commerce fields catalog mapping

When configuring your catalog entity, the Standard fields section lets you map the standard commerce fields to the metadata available in your source. This step is critical for:

Depending on the source you use to index your product inventory, the mapping in this section isn’t always replicated at the source level. See Standard commerce fields mapping for details.

Note

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

Standard commerce fields source mapping

Mapping requirements are different depending 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

When creating a Catalog source, your Coveo organization automatically creates the required standard commerce fields for you, with their source mappings (for example, the ec_name field is automatically created and mapped to the ec_name metadata key).

When structuring your product, variant, and availability data, it’s recommended to use the same field names as the standard commerce fields (prefixed with ec, such as ec_price).

However, your catalog data may use different names to store information that the standard fields expect, such as price.

In this case, you can use the standard commerce fields catalog mapping of the catalog configuration to map the standard commerce fields to the metadata available in your 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"
}

While some product data is stored with the keys that match the created standard fields (ec_name, ec_description, ec_item_group_id, ec_images, ec_category), other data that must fill the standard fields is stored with different keys (brand and price).

Therefore, when mapping standard fields to your catalog, you map the brand and price metadata to the ec_brand and ec_price standard fields.

With a cloud source

When using a SAP, Salesforce, Database, GraphQL API, or REST API source, you must manually map the metadata to the standard commerce fields. As opposed to Catalog sources, this is required even if you already mapped the metadata to the standard fields in the catalog configuration.

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

Catalog structure fields mapping

To structure and configure your catalog entity, you must use a set of stucture 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 and the ec_product_id metadata key for your product’s unique identifier, the value of the ec_product_id field is automatically mapped to the permanentid field. However, if you use a different metadata key for your products' unique identifier, or if you don’t use the Catalog source, you must manually map the unique product identifier to the permanentid 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.