Commerce catalog entity

This is for:

System Administrator

The catalog entity is at the core of a Coveo for Commerce implementation. It establishes relationships between the catalog objects. A catalog entity also lets you standardize your commerce fields to ensure data reliability for Coveo Machine Learning (Coveo ML) models.

Creating a catalog entity is a requirement for enabling Coveo’s machine learning capabilities, maintaining your catalog data, and analyzing Coveo Analytics data through advanced commerce reporting.

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.

Add a catalog entity

There’s a 1:1 relationship between a catalog entity and a product source. This means that each source you created to hold your products must have its own catalog entity. However, sources that contain only items of the availability object type can be shared across multiple catalog entities.

To create a catalog entity:

  1. On the Catalogs (platform-ca | platform-eu | platform-au) page of the Coveo Administration Console, click Add catalog.

  2. Enter a suitable Name for your catalog entity (for example, Barca_Sports_en_US).

  3. Under Object Types, select the catalog objects your catalog entity should include. These object types belong to the catalog configuration that you select in a later step, not to the catalog entity itself. To change them later, change the catalog structure of the configuration, which affects all catalog entities that use it.

    • If your source only contains catalog product data objects (without items of the variant or availability object types), continue to step 4.

    • If your source contains items of the variant object type to handle different variations of a product, select Variants. Note that if you’re solely relying on product groupings to handle different variations of a product, you don’t need to select Variants.

    • If your source contains items of the availability object type to control whether a product or variant is available in a specific channel (for example, a store or a warehouse), select the Availability checkbox.

  4. Under Catalog Content, select the source that contains your catalog data objects. The source you select can only be used with a single catalog entity.

  5. Depending on the way you’ve structured your data, your items of the availability object type might be in another source. In this case, from the dropdown menu, select that source. Otherwise, clear the Use a different source for availabilities checkbox.

  6. (Optional) Use the Project selector to associate this catalog with one or more projects.

  7. To continue selecting a configuration for your catalog, click Next.

Catalog configuration

A catalog configuration establishes the relationship between the different catalog objects. This configuration is re-usable across multiple catalog entities.

When configuring a catalog entity, you can either select an existing catalog configuration or create a new one.

To create a new catalog configuration:

  1. Click Create a New Configuration.

  2. Enter a suitable Configuration name, and then click Next.

  3. Under Define your products, select the objecttype field value that identifies items as products in your catalog data (for example, Product).

    1. Under Select your Product ID metadata, select the metadata key that uniquely identifies each distinct product in your catalog data. Make sure to map this metadata key to the permanentid field in your source. See Mapping to permanentid for details.

  4. If your source contains items of the Variant object type, under Define your variants, select the objecttype field value that identifies items as variants in your catalog data (for example, Variant).

    1. Under Select your Variant ID metadata, select the metadata key that uniquely identifies each distinct variant in your catalog data.

  5. Click Next.

  6. If your data hierarchy contains items of the Availability object type, under Define your availabilities, select the objecttype field value that identifies items as availability channels in your catalog data (for example, Availability).

    1. Under Select your Availability ID metadata, select the metadata key that uniquely identifies each availability channel in your catalog data.

    2. Under Select your Available SKUs metadata, select the multi-value metadata key that lists all sellable items IDs (such as values of ec_product_id or ec_variant_id), available from each distinct availability channel (for example, ec_available_items).

  7. Click Next.

  8. Under Map standard fields to your catalog, map the standard commerce fields to metadata keys from your catalog data. See the Commerce standard fields section for more information on this step.

  9. Click Finish.

The catalog entity is now available on the Catalogs (platform-ca | platform-eu | platform-au) page.

Once your catalog entity is created, push your catalog data into the source once more. This ensures that the catalog entity is properly registered and ensures the proper functioning of Coveo ML models.

Commerce standard fields

In the Map standard fields to your catalog step of the catalog configuration, you’ll be asked to map the standard commerce fields to metadata from your index. This step is critical for:

Warning

catalog configuration mappings aren’t the same as source mappings, in which you map metadata from your source to Coveo fields.

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.

To map the standard commerce fields to your catalog entity, in the Associated Metadata column, select the metadata to associate to the standard fields.

Standard fields mapping in catalog configuration | Coveo for Commerce

If you haven’t pushed your commerce data to your source yet, you won’t be able to see your metadata keys in the dropdowns of the Associated Metadata column. However, if you know the nomenclature of the metadata keys that you’ll be using, you can enter them in the Associated Metadata column.

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.

Edit a catalog entity

You can edit a catalog entity to change its name, the source it uses, the catalog configuration it’s associated with, or the associated facets.

  1. On the Catalogs (platform-ca | platform-eu | platform-au) page, click the desired catalog entity, and then click Edit in the Action bar. This will open the Overview tab where you can:

    • Edit the Name.

    • Edit the Description.

    • Edit the Catalog Content, where you can update the source that contains your catalog data. Note that the source you select can only be used with a single catalog entity.

      If your catalog entity has availability objects and the way you’ve structured your data has changed, your availability data might now be contained in another source. In this case, select the new source from the dropdown menu. Otherwise, clear the Use a different source for availabilities checkbox.

  2. To review facet associations for this catalog entity, select the Facet Association tab. For more information, see the Facet Association section.

  3. Click Save.

  4. When you’re done editing your catalog entity, you must push your catalog data into the source once more. This ensures that the catalog entity is properly registered and ensures the proper functioning of Coveo ML models.

"Facet Association" tab

Using the Facet Association tab, you can quickly view which facetable field names exist for each catalog object type. The percentage shown represents the ratio of each field by catalog object type. By hovering over the percentage shown, you can see the number of documents that contain the associated field name.

Tip

Depending on your specific use case, if the percentages deviate from what you expect, this could be an indication that your data isn’t properly structured.

In advanced use cases, your data structure may require having the same facetable fields on multiple catalog object types. For example, you may want to use the same language field across all your items. In this case, the value @language would need to appear on all catalog objects (Product, Variant, and Availability) to return matching results.

To access the Facet Association tab:

  1. On the Catalogs (platform-ca | platform-eu | platform-au) page, click the desired catalog entity, and then click Edit in the Action bar.

  2. Select the Facet Association tab.

  3. Select the desired field, and then click Edit field in the Action bar. You’ll be sent to the Edit a field subpage, where you can edit the field options.

  4. Click Save.

  5. When you’re done editing your catalog entity, you must push your catalog data into the source once more. This ensures that the catalog entity is properly registered and ensures the proper functioning of Coveo ML models.

  6. (Optionally) Click Refresh Field Cache in the upper-right corner.

    This allows you to instantly update the field values you edited instead of waiting for them to update automatically through the staged refresh, which automatically detects the fields that you can use to generate facets every 15 minutes. The last update time appears at the lower right of the Facet Association tab.

Delete a catalog entity

On the Catalogs (platform-ca | platform-eu | platform-au) page, click the desired catalog entity, and then click Delete in the Action bar.

Project association prompts

A catalog is a resource you can associate with a project. Resources associated with a project can require confirmation when you modify them. These confirmation prompts help prevent accidental changes that could affect a Coveo implementation.

Deleting a resource always requires confirmation, whether it’s associated with a project or not. When the resource is associated with projects, the confirmation prompt lists those projects.

Edit a commerce catalog configuration

You can edit a catalog configuration to rename it, change which objecttype field values identify your catalog objects, remap the standard commerce fields, or change the catalog structure.

A configuration is reusable, so your changes apply to every catalog entity associated with it. The Overview tab lists those catalog entities under Associated Catalogs.

Notes

  • Editing a configuration requires the Edit access level on the Commerce - Catalogs domain, and the Allowed access level on Search - Execute queries to read object types and metadata from your source (see the Required privileges section). Otherwise, the configuration opens in read-only mode.

  • A configuration must be associated with at least one catalog entity before you can open it for editing.

  1. On the Catalogs (platform-ca | platform-eu | platform-au) page, click Manage configurations.

  2. Click external-link next to the configuration you want to edit.

  3. Edit the configuration in the following tabs:

  4. Click Save.

    The Review configuration changes dialog lists every catalog entity your changes affect.

  5. Review the summary, and then click Apply changes.

    • To close the dialog without saving, click Cancel.

    • To discard all your edits, click Cancel at the bottom of the page, and then click Discard unsaved changes.

  6. When you’re done editing the configuration, you must push your catalog data into the source once more. This lets Coveo pick up the configuration changes and process your catalog data accordingly.

Change the catalog structure

The catalog structure determines which catalog objects a configuration defines: products only, products and variants, products and availability channels, or all three.

You change the structure on the configuration, not on the catalog entity. Adding or removing an object type therefore affects every catalog entity that uses that configuration.

Adding Variants to a configuration that’s already in use is a breaking change for products that have no variant items. Variants become the sellable items, so a product with no variant item of its own is left with nothing a customer can purchase.

Important

If your catalog configuration contains variants, it’s essential to ensure that all products have at least one associated variant, even if the product itself doesn’t come in different variations.

In cases where a product has no variations, you must create a variant with minimal information to prevent this variant from appearing as a filtering option for the attached product.

See Variants for products that have no variations to learn how to configure a variant object for a product that has no variations.

To change the catalog structure:

  1. In the Overview tab of the configuration, under Catalog Structure, select or clear the Variants and Availability checkboxes.

    The structure diagram and the configuration tabs update as you make your selection. For example, when you select Availability, the Availability tab appears.

  2. Complete the tabs that your new structure adds.

    You can’t save the configuration until the objecttype field value and the ID metadata key are set for every object type in the structure.

  3. Click Save.

    The Review configuration changes dialog lists each object type you added or removed, what the change means for your implementation, and every catalog entity the change affects.

  4. Review the summary, and then click Apply changes.

  5. When you’re done editing the configuration, you must push your catalog data into the source once more. This lets Coveo pick up the configuration changes and process your catalog data accordingly.

Warning
WARNING

  • Removing any object type deletes its saved settings and field mappings from the configuration, affecting all associated catalog entities. Your indexed catalog data isn’t modified, but you must configure the object type from scratch if you add it back later.

  • Removing availability also removes the purchasing and filtering rules that availability channels provide, so your products are no longer filtered by availability (see Disable availability filtering).

Delete a commerce catalog configuration

Note

You can’t delete a catalog configuration without first deleting the associated catalog entities. Once the associated catalog entity is deleted, the previously associated configuration will remain in your Manage configurations interface until it’s manually deleted.

  1. On the Catalogs (platform-ca | platform-eu | platform-au) page, click Manage configurations.

  2. Click delete next to the configuration you want to delete.

Required privileges

The following table indicates the privileges required for your organization’s groups to view or edit elements of the Catalogs (platform-ca | platform-eu | platform-au) page and its associated panels (see Manage privileges and Privilege reference). The Commerce service is only available to organizations in which Coveo for Commerce features are enabled.

Action Service Domain Required access level

View catalogs

Commerce

Catalogs

View

Content

Fields

View

Sources

View

Organization

Organization

View

Edit catalogs

Commerce

Catalogs

Edit

Content

Fields

View

Sources

View

Organization

Organization

View

Search

Execute queries

Allowed
Note

Granting the Edit access level on a domain also implicitly grants View on that domain.

What’s next?

After configuring your catalog entity, you must associate it with the target tracking ID and locale (see Storefront associations).