Migrate from a source-per-market implementation to a multi-market source

This is for:

Developer System Administrator

In a source-per-market implementation, each market is backed by a dedicated Catalog source containing a localized version of the product documents.

A multi-market source consolidates market-specific values into dictionary fields. Multiple catalog entities can then reference the same source, and each one uses a catalog view definition to specify which dictionary key to read for each field.

This article explains how to migrate a source-per-market implementation to a multi-market source in the same Coveo organization.

For information about configuring a multi-market source, see Multi-market sources.

Important

Contact your Coveo representative before beginning this migration. Coveo must confirm that multi-market sources are enabled for your organization and that your catalog and machine learning configuration are eligible for migration.

Applicability

Warning

This procedure covers migrations performed within an existing Coveo organization. Migrating to a different organization is outside the scope of this procedure.

This procedure applies when:

  • Your organization currently uses separate sources for different markets.

  • The sources contain separate versions of the same products.

  • You want multiple market catalogs to use product documents from a shared source.

  • Market-specific product values can be represented using dictionary fields and catalog view definitions.

  • Product data is indexed into Catalog sources using the Stream API, either directly or through a push-based connector that uses the Stream API, such as SAP Commerce.

The field changes required by this migration apply across the entire Coveo organization. Therefore, the migration affects every source containing documents that use one or more of the fields being converted, even when a source isn’t associated with a storefront included in the migration. You can’t migrate only some of those sources while continuing to send non-dictionary values (a single value instead of key-value pairs) to the same fields from other sources.

Migration overview

Important

Complete every preparation section, from Before you begin through Test the migration, before starting Phase 1, which opens the migration window.

The migration consists of six phases:

Phase Goal

Phase 1: Pause affected ingestion

Stop updates to the affected sources and allow in-flight indexing operations to complete.

Phase 2: Convert the affected fields

Update the affected fields to support market-specific values.

Phase 3: Create and validate the destination source and catalogs

Create and populate the multi-market source and validate the destination catalogs before routing storefront traffic to them.

Phase 4: Cut over query traffic

Route storefront query traffic to the destination catalogs.

Phase 5: Provision and cut over catalog-dependent machine learning models

Replace the machine learning models that depend on the previous catalogs.

Phase 6: Complete the migration

Validate the migrated implementation, then remove the previous resources when they’re no longer required.

The storefront can continue serving queries throughout the migration. However, you must pause document updates to all affected sources while their field configurations are being changed and the new source is being populated.

Before you begin

These tasks establish that the migration is viable for your implementation and that you can both complete and reverse it. Finish them all before you change any resource in the production Coveo organization.

Contact your Coveo representative

Contact your Coveo representative and provide the following information:

  • Your Coveo organization ID.

  • The source IDs of the existing market sources.

  • The catalogs and storefront associations being migrated.

  • The number of market-specific catalogs being consolidated and what distinguishes each market, such as country, language, currency, storefront, or brand.

  • The approximate number of products.

  • The fields that will contain market-specific values.

  • The number of dictionary keys expected in each product document.

  • The machine learning models associated with the existing catalogs.

  • Whether your implementation uses IAPR.

Coveo will confirm whether the organization and implementation are eligible for migration.

Don’t schedule the production migration until Coveo has completed this assessment.

Review multi-market source requirements

Review the Multi-market sources article, including its limitations and considerations.

The destination implementation must use the source, field, catalog, view-definition, and querying configuration supported by that article.

Also review the general Coveo for Commerce setup guide.

SAP Commerce implementations

If you use the Coveo SAP Commerce connector, prepare a separate indexer configuration for the multi-market source before beginning the migration.

The SAP Commerce connector operates in one ingestion mode at a time. Therefore, the source-per-market and multi-market source indexation configurations must not run concurrently on the same SAP Commerce instance.

Before you begin:

  1. Confirm that the existing source-per-market indexer configuration is active and continues to populate the current Catalog sources.

  2. Create the new multi-market source indexer configuration in SAP Commerce.

  3. Confirm that the indexation cron jobs for the new configuration are disabled.

Keep the existing source-per-market indexer configuration ingesting into the current Catalog sources while you complete the preparation work that precedes Phase 1.

Implementations that use the SAP Commerce connector aren’t exempt from Phase 1. The source-per-market indexation cron jobs must be paused along with all other affected ingestion before Phase 2 converts the fields. The previous sources keep serving queries until the cutover in Phase 4, as they do for every implementation.

In Phase 3, after the destination source and catalogs have been created, you’ll disable the existing indexation jobs, set coveo.multimarket.singlesource to true, restart the SAP Commerce instances, and enable the new indexation jobs.

For information about configuring the SAP Commerce connector for a multi-market source, see Multi-market source for SAP Commerce Cloud.

Prepare a migration inventory

Create a record of the current implementation before changing any resources.

For each market, record:

For each affected field, record:

  • field name.

  • field type.

  • Current field configuration.

  • Markets for which the value varies.

  • The dictionary key that will represent each market.

  • Every source containing documents that use the field.

  • Whether the field is used for facets, sorting, ranking, or result display.

This inventory is also required to perform a rollback.

Prepare the storefront authentication

A multi-market implementation requires search token authentication, and it resolves market-specific field values through field aliases. Bring the storefront in line with both before you convert any field.

Replace API-key authentication

If storefront search requests are authenticated directly with API keys, migrate the implementation to search token authentication before starting the source migration.

For more information, see Use search token authentication and Authenticate commerce requests.

Don’t modify the field configurations until the storefront is successfully querying with search tokens.

Authorize dictionary field keys

Update the search token generation process to grant access to the market-specific dictionary fields through the allowedDictionaryFieldKeys property. Without it, the Commerce API can’t resolve the view definition keys, and queries return empty values for those fields.

You can either authorize each field and key explicitly, or use the "*" wildcard as the field name to cover every dictionary field at once. The wildcard must be enabled for your Coveo organization separately from the multi-market sources feature, and it exposes every key of every dictionary field in the index. It’s shorthand for enumerating the fields, not an alternative to search token authentication, which is required either way. For both approaches, and for the restrictions that apply to the wildcard, see Configure the search token.

See also Authorize access to dictionary field keys.

Migrate from dictionary field context

If the implementation uses dictionaryFieldContext or another custom-context mechanism to resolve market-specific field values, migrate it to field aliases before changing the fields.

This step is mandatory for any implementation currently using dictionaryFieldContext. A multi-market source resolves dictionary values through field aliases internally, and an implementation can’t use dictionaryFieldContext and field aliases at the same time.

Warning

If dictionaryFieldContext is still in use when query traffic moves to the destination catalogs in Phase 4, storefront requests fail. Complete this step before the cutover.

For more information, see Use field aliases.

For Commerce API implementations, you don’t specify field aliases in individual storefront requests. Instead, configure a context mapping that routes a context value to a field alias through the FIELD_ALIASES destination. The storefront sends that context value with its queries, and the Commerce API resolves the alias from the commerce context at query time.

Replace empty dictionary keys

field aliases can’t retrieve a dictionary value stored under an empty key such as "".

If the current implementation relies on an empty key as a default value, replace it with an explicitly named key, such as default, before configuring field aliases.

Update the source data, view definitions, and token configuration to use the explicitly named key.

Identify the affected sources

Create a complete list of every source containing documents that use one or more fields being converted.

This list isn’t limited to the dedicated market sources being replaced.

For example, if ec_price will become a dictionary field, every source containing documents that populate ec_price is affected by the field change.

After ec_price is converted, documents that continue sending a single, non-dictionary value to that field will be rejected.

All affected sources must therefore be included in the migration plan.

Prepare the field migration scripts

The keyValue and multilingual settings required by this migration must be changed through the Field API. They aren’t available in the Coveo Administration Console.

See:

The API credential used by the script requires the Edit access level for the Fields domain.

Before applying the migration changes, record the existing configuration of every affected field so that it can be restored by the rollback script.

Prepare the following scripts before starting the migration:

Migration script

Updates the affected fields to the required multi-market configuration. The script should preserve unrelated field settings and can include validation to confirm that the changes were applied successfully.

Rollback script

Restores the affected fields to their original configuration if the migration must be stopped or reverted.

Test both scripts in a non-production organization before the production migration window. Don’t test field configuration changes in the production organization outside the migration window, because field settings apply across the entire organization and could disrupt storefront behavior.

Prepare the multi-market product data

Transform the product data so that market-specific values are represented as dictionaries.

For example, a separate value for each market may be consolidated as follows:

{
  "ec_name": {
    "en_us": "Running shoe",
    "en_ca": "Running shoe"
  },
  "ec_price": {
    "us": 89.99,
    "ca": 119.99
  }
}

The exact dictionary keys must be consistent across:

  • The catalog view definitions.

  • The search token configuration, when you authorize keys explicitly rather than with the "*" wildcard.

  • The multi-market product data.

Configure catalog filters separately using the appropriate values from the multi-value field used to distinguish the products for each catalog.

When ec_name is one of the converted fields, also send a single, non-localized title value in each document, ideally in your main language. See Create the destination source.

For each migrated product, preserve the following identifiers from the existing product documents:

  • ec_product_id

  • permanentid

  • documentId

Don’t generate replacement values for these identifiers during the migration.

Preserving the identifiers maintains continuity between the previous and replacement product documents and helps preserve the relationship with historical commerce events and machine learning data.

You apply this data shape when you generate the documents in Phase 3.

Establish migration stop conditions

Before starting the production migration, define the conditions that require the migration to be stopped or rolled back.

Examples include:

  • A field update fails or produces an unexpected configuration.

  • Documents are rejected because they don’t match the dictionary field structure.

  • Product counts differ unexpectedly between the existing and replacement catalogs.

  • A catalog exposes values belonging to another market.

  • A storefront returns content from the wrong catalog.

  • Commerce API errors increase after a storefront cutover.

  • Storefront telemetry reports new errors, such as errors surfaced by your error monitoring tool.

  • Click-event volume changes unexpectedly, based on the click events your storefront sends.

  • A required machine learning model can’t be provisioned safely.

Assign an owner who has authority to stop the migration. You drive the migration, so this owner is someone on your team rather than at Coveo.

If one of these conditions occurs, see Abort the migration and follow the procedure that matches how far the migration has progressed.

Test the migration

Rehearse the entire procedure before you run it in production.

Complete the migration first in a non-production Coveo organization and, when applicable, a non-production connector environment. Validate both the forward migration and the rollback procedure before repeating the procedure in production.

The test should use:

Phase 1: Pause affected ingestion

Start the migration during an agreed migration window.

  1. Stop all ingestion jobs that send documents to the affected sources.

  2. Prevent scheduled jobs, webhooks, and manual operations from restarting ingestion.

  3. Wait for all in-progress Stream API operations to complete.

  4. Review the source activity and logs for incomplete or failed operations.

  5. Record the time at which ingestion was paused.

  6. Confirm that no affected source is receiving document updates.

The existing sources and catalogs can continue serving query traffic during this phase.

Don’t proceed until all affected ingestion has stopped.

Phase 1 exit criteria

  • Ingestion to all affected sources is stopped.

  • All in-flight indexing operations have completed.

  • No scheduled or regular ingestion process can update the affected sources while the migration continues.

If any criterion isn’t met, don’t continue to Phase 2. No field has been converted yet, so stopping means resuming ingestion into the affected sources, following the ingestion steps in Abort before storefront cutover. The field rollback steps in that procedure don’t apply yet.

Phase 2: Convert the affected fields

Run the prepared field migration script.

For every field that will store market-specific values:

  • Set keyValue to true.

  • For a string field, also set multilingual to true.

  • Leave mergeWithLexicon at its current value.

The multilingual setting applies only to string fields and requires keyValue to be enabled.

The migration doesn’t change mergeWithLexicon. A string field that already had it set to true keeps free-text search after the conversion, because all three parameters are then true. A field that had it set to false was already excluded from free-text search and remains excluded. For more information, see Multilingual system field.

Preserve all unrelated field settings, including applicable facet, sorting, ranking, and result-display settings.

After running the script:

  1. Confirm that the API operation succeeded.

  2. Retrieve each updated field.

  3. Compare the resulting configuration with the expected configuration.

  4. Confirm that only the intended settings changed.

  5. Save the updated field definitions with the migration record.

Don’t restart ingestion into the previous sources. Their existing document payloads will still contain non-dictionary values that no longer match the field configurations.

Phase 2 exit criteria

  • Every affected field has the expected dictionary configuration.

  • No unrelated field setting changed.

  • No affected source has resumed ingestion.

  • The rollback script still contains the original field definitions.

If any criterion isn’t met, don’t continue to Phase 3. See Abort before storefront cutover.

Phase 3: Create and validate the destination source and catalogs

Create the destination Catalog source and the market catalogs that will use the shared multi-market product documents.

Create the destination source

Create a Catalog source for the multi-market product documents, as described in Add a Catalog source.

If ec_name is one of the fields you converted in Phase 2, it can no longer populate the single-value title field that the Content Browser (platform-ca | platform-eu | platform-au) uses to display product titles. Remove the default ec_name-to-title source mapping on the destination source, and send a default title value in your catalog data instead. For details, see Configure dictionary fields.

Leave the mapping in place on the previous market sources. They stay frozen from Phase 1 until you delete them in Phase 6, so the converted field doesn’t affect the titles they already display.

Create the market catalogs

Create one catalog for each market being migrated. Configure each catalog to reference the new Catalog source.

For each catalog:

  1. Configure the appropriate catalog filter.

  2. Configure the catalog view definition.

  3. Ensure that the dictionary keys referenced by the view definition match the keys used in the source data and search-token configuration.

For information about configuring catalogs for a multi-market source, see Multi-market sources.

Generate the multi-market product documents

Generate the product documents using the data shape you defined in Prepare the multi-market product data, targeting the dictionary fields configured for the destination implementation.

Don’t change the dictionary keys at this stage. They must still match the catalog view definitions and the search token configuration.

Ingest the multi-market product data

How you ingest the product data depends on how your implementation sends data to Coveo.

Direct Stream API implementations

Push the transformed multi-market product documents to the new Catalog source.

For information about sending catalog data through the Stream API, see Push and update your catalog data.

Wait for indexing to complete before validating the destination catalogs.

SAP Commerce implementations

The SAP Commerce connector operates in one ingestion mode at a time, so populating the destination source means switching the connector to its multi-market source configuration. The previous sources stopped ingesting in Phase 1 and keep serving storefront queries until the cutover in Phase 4.

  1. Confirm that:

    • The destination Catalog source and catalogs are configured.

    • The catalog filters and view definitions are configured.

    • The multi-market source indexer configuration is ready.

    • The indexation cron jobs for the multi-market source configuration are disabled.

  2. Disable the indexation cron jobs for the existing source-per-market indexer configuration.

  3. Change coveo.multimarket.singlesource from false to true.

  4. Propagate the updated property value to every SAP Commerce instance.

  5. Restart each SAP Commerce instance so that the connector uses the updated property value.

  6. Enable the indexation cron jobs for the multi-market source indexer configuration.

  7. Run the required indexation to populate the destination Catalog source.

  8. Wait for indexing to complete.

Don’t run the source-per-market and multi-market source indexation configurations concurrently.

For information about configuring the SAP Commerce connector, see Multi-market source for SAP Commerce Cloud.

Validate the destination catalogs

Preview each destination catalog after the new source has been fully indexed. On the Catalogs (platform-ca | platform-eu | platform-au) page of the Coveo Administration Console, select the catalog entity, and then review its content on the Overview tab of the panel that opens. When the catalog contains availability data, use the View Products and View Availabilities options to switch between the two previews.

Validate that:

  • The expected products are included in each market.

  • Products that shouldn’t be available in a market are excluded.

  • Market-specific names, descriptions, prices, currencies, and availability values are correct.

  • Values from one market don’t appear in another market.

  • ec_product_id, permanentid, and documentId remain consistent with the existing implementation.

  • Indexing completed without unexpected errors.

Validate the catalog content itself at this stage. storefront behavior, including facet selections and sorting, is validated in Phase 4, after the storefront associations point to the destination catalogs.

Don’t move storefront query traffic until the destination source is fully indexed and the destination catalogs have passed validation.

Phase 3 exit criteria

  • The destination Catalog source and market catalogs are configured, including their catalog filters and view definitions.

  • The destination source is fully indexed.

  • Indexing completed without unexpected errors.

  • Each destination catalog returns the expected products and market-specific values.

  • Stable product identifiers have been preserved.

  • The existing storefront associations still reference the existing catalogs.

  • For SAP Commerce implementations:

    • coveo.multimarket.singlesource is set to true on every instance.

    • Every SAP Commerce instance has been restarted with the updated configuration.

    • The multi-market source indexation cron jobs are enabled.

    • The source-per-market indexation cron jobs are disabled.

If any criterion isn’t met, don’t continue to Phase 4. No storefront is querying a destination catalog yet, so the migration can still be reversed without affecting shoppers. See Abort before storefront cutover.

Phase 4: Cut over query traffic

The destination source is populated and validated at this point, for every implementation. This phase routes storefront query traffic to the destination catalogs, one storefront at a time.

Before moving any storefront, confirm that the implementation no longer uses dictionaryFieldContext. Requests fail if it’s still in use when the storefront targets a destination catalog. See Migrate from dictionary field context.

Move storefronts to the destination catalogs

Move storefronts to the new catalogs one at a time. For more information, see Storefront associations.

For each storefront:

  1. Record the existing storefront association.

  2. Update the association to reference the corresponding destination catalog.

  3. Allow up to one minute for the association change to propagate.

  4. Verify that the storefront targets the destination catalog.

  5. Run the storefront validation tests.

  6. Monitor the storefront before moving to the next association.

Don’t change all storefront associations simultaneously.

Validate each storefront

For each changed association, test:

  • Search requests.

  • Product listing requests.

  • Query suggestions.

  • Product recommendation requests.

  • Representative facet selections.

  • Representative sorting options.

  • Queries that return market-specific products.

  • Queries for products that should be excluded from the market.

Confirm that:

  • The expected catalog is queried.

  • The correct market-specific values are returned.

  • Content from other markets isn’t exposed.

  • facets and sorting continue to work.

  • The storefront doesn’t report new client-side errors.

  • Analytics events continue to be sent with the expected tracking ID and locale.

After the functional validation, monitor the storefront against the migration stop conditions you defined before starting.

Proceed to the next storefront only after the current storefront has passed validation.

Roll back a storefront association

If a storefront fails validation:

  1. Restore its previous storefront association.

  2. Allow up to one minute for the rollback to propagate.

  3. Confirm that the storefront once again queries the previous catalog.

  4. Validate the restored storefront.

  5. Investigate and correct the issue before attempting the cutover again.

Restoring a storefront association rolls back query traffic for that storefront. It doesn’t restore ingestion to the previous sources.

For SAP Commerce implementations, don’t re-enable the source-per-market indexation cron jobs while the connector remains configured for multi-market source ingestion. If you need to resume ingestion to the previous sources, perform the SAP Commerce ingestion rollback.

Contact Coveo before continuing when the cause of a failed validation isn’t understood.

Resume or confirm regular ingestion

After every storefront has been moved successfully, ensure that regular product updates are sent only to the multi-market source.

Direct Stream API implementations

  1. Enable the regular ingestion process that generates multi-market documents.

  2. Confirm that no regular ingestion process targets the previous sources.

  3. Send a controlled update to a small set of products.

  4. Confirm that the update is indexed and resolved correctly in every applicable catalog.

  5. Resume normal update volume.

SAP Commerce implementations

  1. Confirm that the multi-market source indexation cron jobs are enabled.

  2. Confirm that the source-per-market indexation cron jobs remain disabled.

  3. Send or trigger a controlled update to a small set of products.

  4. Confirm that the update is indexed in the multi-market source and resolved correctly in every applicable catalog.

  5. Resume the normal SAP Commerce indexation schedule.

Monitor indexing errors during the first regular update cycle.

Phase 4 exit criteria

  • Every storefront association points to its destination catalog.

  • Every storefront passes functional validation.

  • Commerce API and storefront telemetry show no unexpected errors.

  • Click-event volume hasn’t changed unexpectedly.

  • Regular product updates are being sent only to the multi-market source.

  • The previous sources and catalogs remain available for rollback.

If a single storefront fails validation, see Roll back a storefront association. If any other criterion isn’t met, don’t continue to Phase 5. See Abort during storefront cutover.

Phase 5: Provision and cut over catalog-dependent machine learning models

After the storefronts have been moved to the destination catalogs, create replacement machine learning models for any models that depend on catalog data.

The previous models stay associated with their query pipelines and keep serving queries while the replacement models train, so model behavior isn’t interrupted during this phase.

Replacing a catalog-dependent model doesn’t reset personalization. models train from a catalog and a tracking ID, so a model can be recreated against a different catalog without a personalization cold start, as long as the tracking ID stays the same. Keep the existing tracking IDs throughout the migration: a user’s history of actions is tied to a tracking ID, so changing one disconnects users from that history.

Only catalog-dependent models need to be replaced. machine learning models that don’t depend on catalog data can remain unchanged.

A model is catalog-dependent when it trains from catalog data. Catalog-dependent Commerce models include:

Review every model that the implementation uses against that criterion, including any model that isn’t listed here. For more information, see Commerce models.

Create replacement models

For each catalog-dependent model used by the implementation:

  1. Record the existing model and the catalog it uses.

  2. Create a replacement model configured to use the corresponding destination catalog.

  3. Keep the existing model associated with the query pipeline while the replacement model trains.

Don’t delete the existing models at this stage. Keep them available until the replacement models have been validated.

Wait for the replacement models to train

Wait for each replacement model to finish training before associating it with a query pipeline.

Training time depends on factors such as the number of products in the catalog and the volume of historical event data.

Don’t proceed with a model until it has completed training.

Cut over the models

For each relevant query pipeline:

  1. Record the current model associations.

  2. Replace the previous catalog-based model with the replacement model and save the change.

  3. Confirm that only one model of each type is associated with the query pipeline.

  4. Run representative queries or recommendation requests.

  5. Confirm that the replacement model returns valid responses.

  6. Monitor the storefront for errors or unexpected behavior.

Change and validate one model type at a time.

Don’t delete the previous model until the replacement has passed validation.

Phase 5 exit criteria

  • Every required catalog-dependent model has been recreated using the destination catalogs.

  • Every replacement model has completed training.

  • Each relevant query pipeline uses the replacement catalog-dependent models.

  • Only one model of each type is associated with each relevant query pipeline.

  • Representative queries and recommendation requests return valid responses.

  • No unexpected storefront errors or behavior are observed after the model changes.

  • The previous catalog-dependent models remain available for rollback.

If a replacement model fails validation, see Roll back the affected model. If any other criterion isn’t met, don’t continue to Phase 6. If the investigation identifies a broader problem, see Reverse the complete migration.

Phase 6: Complete the migration

Keep the previous resources during an agreed observation period.

During this period, continue monitoring:

  • Commerce API errors

  • Indexing errors

  • Storefront telemetry

  • Click-event volume

  • Catalog content

  • machine learning responses

Warning

Deleting the previous resources is irreversible and ends the ability to roll back the migration.

Before you begin, confirm that the observation period completed without triggering any of the conditions you defined in Establish migration stop conditions, that the Phase 4 and Phase 5 exit criteria still hold, and that every storefront still passes the storefront validation checks.

This is the last point at which the migration can be reversed. If any of those checks fail, see Abort the migration instead of continuing.

After the destination implementation has been accepted on that basis, remove the previous resources in the following order:

  1. Delete the previous catalog-based machine learning models.

  2. Delete the previous catalogs.

  3. Delete the previous dedicated market sources.

Removing the resources in this order prevents a model or catalog from referencing a resource that has already been deleted.

After cleanup:

  1. Confirm that normal indexing is continuing.

  2. Confirm that every storefront still targets the expected catalog.

  3. Archive the migration inventory and field-configuration backups.

  4. Update internal operational procedures to reference the multi-market source.

  5. Notify Coveo that the migration has been completed.

Abort the migration

The migration is designed to be interruptible before the previous resources are deleted.

Contact Coveo when stopping or restarting the migration.

Roll back SAP Commerce ingestion

If you use the Coveo SAP Commerce connector, reversing ingestion requires switching the connector back to its source-per-market configuration:

  1. Disable the indexation cron jobs for the multi-market source indexer configuration.

  2. Revert coveo.multimarket.singlesource from true to false on every SAP Commerce instance.

  3. Restart each SAP Commerce instance so that the connector uses the reverted property value.

  4. Re-enable the indexation cron jobs for the source-per-market indexer configuration.

This procedure requires the previous dedicated market sources to still exist in your Coveo organization. Once you delete them in Phase 6, ingestion can no longer be rolled back.

Perform these steps wherever an abort procedure below says to resume ingestion into the previous sources. Everything else in each abort procedure is the same for SAP Commerce implementations as for direct Stream API implementations.

Abort before storefront cutover

When no storefront associations have been changed:

  1. Stop ingestion into the multi-market source.

  2. Run the field rollback script.

  3. Confirm that the original field configurations have been restored.

  4. Resume ingestion into the previous sources. For SAP Commerce implementations, this requires the SAP Commerce ingestion rollback.

  5. Send a controlled product update.

  6. Confirm that the update indexes successfully.

  7. Validate the existing storefronts.

Abort during storefront cutover

When some storefront associations have already been changed:

  1. Stop ingestion into the multi-market source.

  2. Restore each changed storefront association to its previous catalog.

  3. Allow up to one minute for each restored association to propagate.

  4. Confirm that all storefronts query their previous catalogs.

  5. Run the field rollback script.

  6. Confirm that the original field configurations have been restored.

  7. Resume ingestion into the previous sources. For SAP Commerce implementations, this requires the SAP Commerce ingestion rollback.

  8. Send a controlled product update.

  9. Validate indexing and storefront behavior.

Abort after machine learning cutover

Once models have been replaced, two rollback scopes are available. Reversing the model change is usually enough, and it leaves the rest of the migration in place. Reverse the complete migration only when the investigation identifies a broader problem.

Roll back the affected model

Use this procedure when the issue is limited to a replacement machine learning model.

If an issue occurs after replacing a model, first roll back that model change:

  1. Replace the affected replacement model with the previous model and save the change.

  2. Confirm that only the previous model of that type is associated with the query pipeline.

  3. Validate the affected queries or recommendation requests.

  4. Investigate and correct the issue before attempting the model cutover again.

You don’t need to roll back the storefront associations, field configuration, or ingestion when the issue is limited to a replacement machine learning model.

Reverse the complete migration

This procedure reverses every change the migration made, including the model, storefront, and field changes.

If the investigation identifies a broader issue that requires the complete migration to be reversed:

  1. Stop ingestion into the multi-market source.

  2. Restore all previous machine learning model associations.

  3. Confirm that only the previous model of each type is associated with the relevant query pipelines.

  4. Restore the previous storefront associations.

  5. Allow up to one minute for the associations to propagate.

  6. Restore the original field configurations.

  7. Resume ingestion into the previous sources. For SAP Commerce implementations, this requires the SAP Commerce ingestion rollback.

  8. Validate the previous catalogs, storefronts, and models.

Don’t delete the destination source, catalogs, or models until the rollback has been validated and Coveo confirms that they can be removed.