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 commerce catalog structure fields and creating 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 commerce catalog, the Standard fields section lets you map the standard commerce fields to the metadata available in your source. This procedure lets PAYG models target and learn from the right content.

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.

Make sure the metadata in these fields is accurate and up-to-date before indexing it in your Coveo organization.

With a Catalog source

When creating a Catalog source, your Coveo organization automatically creates the required standard commerce fields for you. It also creates the ec_product_id field to uniquely identify the items in your source.

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. This mapping will be replicated at the source level.

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 Coveo commerce catalog, you must create a set of fields for the items in your source.

When structuring your product, variant, and availability data, you should use the recommended field names, such as using sku to uniquely identify variant items in your source. However, your catalog data may use different names, such as variantid, to store the information that the catalog structure fields expect.

You must ensure that these fields are mapped with corresponding metadata from the items in your source.

Example

As recommended in Commerce catalog structure fields, you created the following fields to enforce your catalog structure:

  • objecttype

  • sku

  • availabilityid

  • availableskus

In your catalog data, the metadata that must fill these fields is stored with different keys. For example, the unique identifier of each variant is stored with the variantid key.

Therefore, you create a mapping rule that maps the variantid metadata to the sku field.

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.

If you use the automatically created ec_product_id field as the unique product identifier, you should map ec_product_id to the permanentid field.

Tip

If you use the sku structure field as the unique product identifier in a catalog with no variants, then you should map that field to the permanentid field instead.

Additional fields mapping

In addition to the standard commerce 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 Coveo 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 Coveo 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.