Add a Catalog source

This is for:

System Administrator

The first step in indexing your content is to create a Catalog source that will hold all your catalog data in the Coveo index.

A Catalog source contains items designed to be sold. It can also contain variants, availability channels, or entitlement information.

Note

Coveo also offers solutions to index content residing in SAP Commerce Cloud and Salesforce Commerce Cloud.

See the following sections for instructions:

It’s also possible to index commerce-specific content using a Salesforce, REST API, Database, or GraphQL API source. However, additional setup is required. Contact your Customer Success Manager to discuss your options.
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.

It’s recommended to create separate product sources for each locale you’re supporting.[1]

This allows the Coveo ML models to learn independently from each experience. Such a setup will result in recommendations that are optimally personalized to users' preferences and search behavior on each website in your multi-catalog structure.

Example

The company Barca sells products in Canada and the US. In Canada, they support French and English. In the US, they support English and Spanish.

They have the following storefronts:

  • Barca Canada (www.barca.com/ca/). This storefront supports French (www.barca.com/ca/fr/) and English (www.barca.com/ca/en/).

  • Barca US (www.barca.com/us/). This storefront supports English (www.barca.com/us/en/) and Spanish (www.barca.com/us/es/).

This setup requires the creation of four {resource-type}:

  • One for the English variation of the Canadian storefront.

  • One for the French variation of the Canadian storefront.

  • One for the English variation of the US storefront.

  • One for the Spanish variation of the US storefront.

Note

Some setups require an additional source to index items of the availability catalog object. See Source configuration approaches for availability channel for details.

1. Having a separate source for each locale you’re supporting will likely lead to content duplication. This could affect your product entitlements.

Add a Catalog source

Follow the instructions below to add a Catalog source.

  1. On the Sources (platform-ca | platform-eu | platform-au) page, click Add source.

  2. In the Add a source of content panel, click the Catalog source tile.

  3. Configure your source.

Tip
Leading practice

It’s best to create or edit your source in your sandbox organization first. Once you’ve confirmed that it indexes the desired content, you can copy your source configuration to your production organization, either with a snapshot or manually.

See About non-production organizations for more information and best practices regarding sandbox organizations.

"Configuration" tab

In the Add a Catalog Source panel, the Configuration tab is selected by default. It contains your source’s general and authentication information, as well as other parameters.

General information

Source name

Enter a name for your source.

Tip
Leading practice

A source name can’t be modified once it’s saved, therefore be sure to use a short and descriptive name, using letters, numbers, hyphens (-), and underscores (_). Avoid spaces and other special characters.

When coding a crawler to push content in this source, a developer will need this name to get the corresponding sourceId from the Sources (platform-ca | platform-eu | platform-au) page.

Stream API URL

Available only when accessing an existing Catalog source, the input contains the URL you must use to push your catalog data in your source. The URL has the following form:

https://api.cloud.coveo.com/push/v1/organizations/<ORGANIZATION_ID>/sources/<SOURCE_ID>/stream/open

The URL that you can Copy to clipboard contains your <ORGANIZATION_ID> and <SOURCE_ID>, which are required parameters to stream your catalog data in your source. See the Stream section in Push API to test API calls.

API key

An API key with adequate privileges is required to push and update your catalog data. A user with Edit access on the API keys domain can create a Catalog source API key in the following ways:

  • When creating the Catalog source by selecting the Create an API key checkbox.

    • Once the source is saved, the API key successfully created dialog appears and lets you view and copy the value of the API key. This dialog appears only once. If the key’s value isn’t retained, a new API key can be created in one of the other ways listed in this section.

      API key checkbox in source configuration panel | Coveo
    Note

    If the Catalog source you’re creating has the Same users and groups as in your current permission system Content security option selected, an error occurs if the following conditions are met:

    • The Create an API key checkbox is selected.

    • You don’t have the necessary content security-related privileges.

  • By selecting a specific source on the Sources (platform-ca | platform-eu | platform-au) page, and then selecting Create API key from the Action bar. This method also ensures that the key has the proper privileges required to push content to the source.

    Creating a Push source API key | Coveo

  • From the API Keys (platform-ca | platform-eu | platform-au) page. You can create a new key for the source or assign an existing API key to it. When using this method, make sure that the proper privileges are given to the key. See the following table for the required privilege set depending on the Content Security option selected for the source.

    Granted API key privileges Everyone content security Same users and groups as in your current permission system content security

    Content > Push items to sources > Custom (Allow on target source)

    check

    check

    Content > Sources > View all

    check

    check

    Organization > Organization > View

    check

    check

    Content > Push identities to security providers > Allow for all providers

    check

    Content > Security identity providers > View

    check
Tip
Leading practice

Deactivate or delete all unused API keys assigned to your source.
Project

Use the Project selector to associate your source with one or more Coveo projects.

"Content Security" tab

Select who will be able to access the source items through a Coveo-powered search interface. For details on this parameter, see Content security.

Note

If you make your source secure by selecting the Same users and groups as in your current permission system content security option, your crawler process must push item permissions along with the content (see Manage security identities in a security identity provider and Manage items and permissions in a Push source).

"Access" tab

In the Access tab, specify whether each group (and API key, if applicable) in your Coveo organization can view or edit the current source.

For example, when creating a new source, you could decide that members of Group A can edit its configuration, while Group B can only view it.

For more information, see Custom access level.

Required privileges

You can assign privileges to allow access to specific tools in the Coveo Administration Console. The following table indicates the privileges required to view or edit elements of the Sources (platform-ca | platform-eu | platform-au) page and associated panels. See Manage privileges and Privilege reference for more information.

Note

The Edit all privilege isn’t required to create sources. When granting privileges for the Sources domain, you can grant a group or API key the View all or Custom access level, instead of Edit all, and then select the Can Create checkbox to allow users to create sources. See Can Create ability dependence for more information.
Actions Service Domain Required access level

View sources, view source update schedules, and subscribe to source notifications

Content

Fields

View

Sources

Organization

Organization

Edit sources, edit source update schedules, and edit source mappings

Organization

Organization

View

Content

Fields

Edit

Sources

View and map metadata

Content

Source metadata

View

Fields

Organization

Organization

Content

Sources

Edit

What’s next?

Now that you’ve created your Catalog source, you should make sure that your Coveo organization contains all the required fields. Proceed to Commerce fields for more information.