Multi-market source for SAP Commerce Cloud

This is for:

Developer System Administrator

This article explains how to configure the Coveo SAP Commerce extensions to use a multi-market source: a single Catalog source that powers multiple markets (languages, currencies, or countries) instead of a dedicated source for each market. This mode is the SAP Commerce Cloud connector’s implementation of the broader multi-market sources capability, and is available in the v3 and v4 branches only.

The SAP Commerce connector setup is the same for both ingestion modes. Follow Push data to Coveo (SAP Commerce Cloud 2011 or later) for the complete connector setup, then apply the following differences for a multi-market source:

All other connector configuration (installation, credentials, search provider, index configuration, cron jobs, field mappings, and the remaining value providers) is identical to the standard setup.

For the Coveo organization side of the setup (dictionary fields, catalog view definitions, catalog filters, and search tokens), see Multi-market sources.

Important

The multi-market source mode relies on the multi-market sources feature, which is in early access. Contact your Coveo representative to have it enabled for your Coveo organization.

About the ingestion modes

The connector has two modes of operation. You select the mode for each CoveoSearchSnSearchProviderConfiguration item, which owns a set of sources and is referenced by a CoveoSnIndexConfiguration.

Because the mode is set per search provider configuration rather than per instance, a single SAP Commerce instance can run both modes at the same time, using one configuration for each. This is what makes it possible to populate a multi-market source while the existing source-per-market configuration keeps running.

Mode 1: Source-per-market implementation

Market-specific values are pushed to separate Catalog sources, one per market. For example, for a storefront with two markets, the connector pushes each product to two sources, with market A values going to source A and market B values going to source B. This mode is also used for single-market setups.

Mode 2: Multi-market source

A single Catalog source holds market-specific values (such as name, description, and price) as dictionary fields. The connector pushes one product item, with localized values stored as key-value pairs, to one source.

Choose a mode

Use the following guidance to decide which mode fits a given implementation:

  • Single market, with no plans to add markets: Use mode 1. Mode 2 adds configuration overhead even for a single market (for example, catalog view definitions and search tokens), so there’s no benefit to it when a client serves one market and doesn’t expect to expand.

  • Single market, but likely to add markets later: Consider starting with mode 2.

  • Multiple markets: Use mode 2 to power all markets from a single source, or mode 1 to use a separate source per market.

Note

This guidance should be applied at the discretion of the team handling the implementation. Contact your Coveo representative if you’re unsure which mode suits your deployment.

Prerequisites

Enable the multi-market source mode

The connector mode is controlled by the isSingleSourceMultiMarket attribute on the CoveoSearchSnSearchProviderConfiguration item. Because this attribute is data rather than a property, you set it with impex alongside the rest of your search provider configuration:

INSERT_UPDATE CoveoSearchSnSearchProviderConfiguration; id[unique = true]; name; coveoSource(&sourceId); isSingleSourceMultiMarket
; $coveoSearchProviderConfiguration; Coveo Search Provider Configuration; source1,source2; true

Set the value according to the implementation:

Implementation isSingleSourceMultiMarket Mode

Multi-market, single source

true

Mode 2

Multi-market, multiple sources

false

Mode 1

Single market, single source

false

Mode 1

The attribute is optional and defaults to false, so a configuration that doesn’t set it runs in mode 1.

Important

Setting isSingleSourceMultiMarket to true isn’t sufficient on its own. The two modes have different, enforced source requirements, so the sources and the CoveoSnIndexConfiguration must be aligned with the mode before the indexer runs. See Configure the product source.

Connector version requirements

The isSingleSourceMultiMarket attribute requires connector version 4.1.0 or 3.5.0.

On earlier versions, the mode is controlled instead by a global coveo.multimarket.singlesource property set in your project’s local.properties file. That property applies to every index in the instance, can’t be mixed across configurations, and is read only when the instance starts, so changing it requires a restart.

Warning

When you upgrade to 4.1.0 or 3.5.0, coveo.multimarket.singlesource is removed and ignored, and the new attribute defaults to false.

An implementation that was running in mode 2 therefore reverts to mode 1 unless you set isSingleSourceMultiMarket to true on its search provider configuration. Include that change in the same deployment as the upgrade.

Configure the product source

In the standard setup, each CoveoSource specifies the language, currency, and country it applies to:

INSERT_UPDATE CoveoSource; id[unique = true]; name[unique = true]; language(isocode); currency(isocode); country(isocode); objectType(code); consumedDestination(id)
; electronics-zh-USD-US-source; Electronics Chinese Dollar USA Source; zh; USD; US; PRODUCTANDVARIANT; electronics-zh-USD-US-dest

Because a multi-market source holds the values for all markets, these qualifiers aren’t needed. Leave the language, currency, and country columns empty:

INSERT_UPDATE CoveoSource; id[unique = true]; name[unique = true]; language(isocode); currency(isocode); country(isocode); objectType(code); consumedDestination(id)
; electronics-zh-USD-US-source; Electronics Chinese Dollar USA Source; ; ; ; PRODUCTANDVARIANT; electronics-zh-USD-US-dest

Leave the qualifiers unset on the source only. The CoveoSnIndexConfiguration tells SAP Commerce which languages, currencies, and countries to push, so it must still list every market the implementation serves, in both modes.

For a complete mode 2 configuration, see the electronics-multimarket-singlesource-configuration-example.impex example file in the connector code base. You can use it as a template to fill with your data and configure your project faster.

Source requirements for each mode

The connector validates the sources against the configured mode before the indexer runs, and the indexer job fails if the configuration doesn’t match.

Only sources whose objectType is PRODUCTANDVARIANT are validated. A separate AVAILABILITY source is unaffected by these requirements and doesn’t count toward the single-source limit, which is why the mode 2 example configures two sources.

isSingleSourceMultiMarket Requirements for PRODUCTANDVARIANT sources

true

Exactly one source, with language, currency, and country all empty.

false

Every source must set language, currency, and country, and each of those values must be one of the values listed on the CoveoSnIndexConfiguration.

If validation fails, the indexation job fails with one of the following errors:

Single source mode is enabled but multiple sources have been configured

This error means that more than one PRODUCTANDVARIANT source is attached to a configuration with isSingleSourceMultiMarket set to true.

The following sources are not configured for the job: [electronics-product-source]

This error means that the listed sources don’t meet the requirements for the configured mode. In mode 2, check that the qualifiers are empty. In mode 1, check that each qualifier is set and matches a value on the CoveoSnIndexConfiguration.

Configure the item title

In mode 1, a product’s name and content-browser title are identical, so the connector reuses the mandatory name value for both.

In mode 2, this is no longer true: ec_name is a localized dictionary field (a map of localized values), while the title shown for the item in the Content Browser (platform-ca | platform-eu | platform-au) must be a single string. To resolve this, use the coveoMultiMarketSingleSourceDocumentTitleSnIndexerValueProvider value provider to set the specific language used for the item title.

Configure the value provider through the valueProviderParameters:

  • defaultLanguage sets the language used for the title (for example, zh).

  • expression sets the model attribute used to populate the title value (for example, name).

Because the title now comes from this value provider, you also configure the dictionary field that maps to ec_name. The following example configures both the name (title) and ec_name fields:

INSERT_UPDATE SnField; indexType(id)[unique = true]; id[unique = true]; name; fieldType(code); localized[default = false]; valueProvider; valueProviderParameters[map-delimiter = |]; qualifierTypeId
; $coveoProductIndexType; name; Name; TEXT; true; coveoMultiMarketSingleSourceDocumentTitleSnIndexerValueProvider; defaultLanguage->zh|expression->name; ;
; $coveoProductIndexType; ec_name; EC_Name; TEXT; true; productAttributeSnIndexerValueProvider; expression->name;
Note

When an SnField is configured as localized, the standard SAP Commerce value providers return a map of localized values. In mode 2, the connector pushes that map as a dictionary field. In mode 1, the connector instead determines the localized value relevant to each per-market source. This is why ec_name is configured as a localized dictionary field in mode 2.