Migrate Changes Between Cloud Organizations

Coveo for Sitecore deployments being complex, they involve a fair amount of configuration, experimentation, and evaluation. In large implementations, Coveo for Sitecore developers typically work together on ideas over multiple local setups, merge their changes in a sandbox environment for final testing, before applying these changes in production. Your development needs and the size of your implementation dictate the number of Coveo organizations you need (see Have Multiple Development Environments and Non-Production Organization Reference).

A great deal of the power Coveo for Sitecore delivers comes from Coveo features. Consequently, Coveo for Sitecore developers should spend a fair amount of their time optimizing Coveo resource configurations and promoting their changes, whether from a trial organization to a sandbox organization, or from sandbox to production. When starting a new development iteration, development team members may want to replicate the production Coveo organization resource configurations to make these their new base point. Being able to bulk copy resource configurations between organizations ensures configuration identicalness and saves time. That’s what makes the Resource Snapshot functionality so useful.

Types of Resources You Can Include in a Snapshot

Resource snapshots let you copy the configuration of several types of resources (e.g., query pipelines, indexing pipeline extensions (IPE), hosted search pages , Coveo Machine Learning (Coveo ML) models).

The snapshot feature is still at its beta stage, and not all resource types can be included in a snapshot yet. Coveo will progressively release updates to ultimately allow you to include all resources in your organization.

There’s no value in using resource snapshots to copy fields into a Coveo organization that’s being used to index a Sitecore instance. Snapshots do enable you to copy Coveo fields between organizations. However, the selection of Sitecore fields to be indexed and the mapping of Sitecore fields with Coveo fields is all managed within the Sitecore instance, either through .config files or using the Command Center Indexing Manager.

Creating and Applying Resource Snapshots

Creating and copying configurations using the resource snapshot feature is a three-step process.

1. Creating a Snapshot

The instructions below allow you to create a snapshot of resources in the source organization in its current state.

To generate a snapshot:

  1. On the Resource Snapshots page, click Create Snapshot, and then select Of your organization.

  2. In the Create Snapshot of Your Organization panel that appears, you can choose to clear the Include dependencies automatically box. When the box is checked, your snapshot includes not only the desired resources, but all other resources that depend on them. For example, a snapshot of a query pipeline would also include the rules of this pipeline and the machine learning models associated with it. The Include dependencies automatically box is checked by default, as we recommend including dependencies in your snapshot to ensure that the resources you copy to a different organization work identically to those in the original organization.

  3. Select the resources to include in your snapshot. If you want to index only some resources, specify the desired resources.

  4. Enter a descriptive name for your snapshot. This description will appear on the Resource Snapshots page.

  5. Click Create snapshot or, alternatively, click Save for CLI to download your selection for usage in Coveo CLI.

2. Sending the Snapshot

Next, still in your source Coveo organization, you want to send the snapshot to the destination Coveo organization.

  1. On the Resource Snapshots page, select the desired snapshot, and then, in the Action bar, click Export.

  2. In the Export Snapshot panel that opens, select a destination organization.

  3. Enter a descriptive name for your snapshot. This description will appear on the Resource Snapshots page of the destination organization.

  4. Click Export.

3. Applying the Snapshot

You can now switch to your destination Coveo organization and apply the snapshot.

  1. On the Resource Snapshots page, select the desired snapshot, and then, in the Action bar, click Open.

  2. On the snapshot subpage, you can review the resources in the snapshot in the Content tab.

  3. In the Overview tab, under Step 1 - Check prerequisites, click Check prerequisites. If Coveo finds missing vault values, click Import vault parameters to import them from the origin organization. Vault key-value pairs are crucial, secret pieces of information used to migrate sensitive data leveraged by your resources, such as credentials used to index content. If the Import vault parameters button doesn’t show up, the vault key-value pairs are impossible to import. For instance, they could have been deleted from the origin organization. Click Create vault entries via API to add them manually instead.

  4. Under Step 2 - Validate snapshot, click Validate snapshot to generate a report of the changes to apply, and then check that the resources will be added and updated as expected. Should you notice errors, under Synchronization, click Update to fix the resource associations. We then recommend to generate and check a new report. Some errors may also be due to a limit that has been reached.

  5. Once your snapshot has been validated, it’s ready to be applied. Under Step 3 - Apply changes, click Apply changes to apply the snapshot to your organization.

Coveo provides an API you can use to perform resource snapshot-related tasks programmatically.

Resource Snapshots Creation and Application Under the Hood

A resource snapshot consists in a JSON file listing the resources you decided to include, as well as their configuration.

The resources object contains arrays named after the types of resources you included in the snapshot (e.g., EXTENSION). These arrays contain the configuration data of each resource in the snapshot. Resources are identified with their resource name, which is a unique identifier across organizations. Two resources in different organizations with an identical resource name are considered to be analogous, i.e., two versions of the same resource.

Coveo therefore maintains a table of associations between a resource ID, which identifies a resource in a given organization, and its resource name, which is a unique identifier across organizations.

A resource in a destination organization can only be altered if the applied snapshot contains a resource with the same resource name.

Association Table Update

When you create a resource snapshot, Coveo generates a JSON list of the resources to export. Each resource in the snapshot is identified with its platform-wide resource name, which is generated for this purpose if the resource doesn’t already have one. Then, when you apply the snapshot, Coveo matches the resource names in the snapshot with the IDs of the resources in the organization. The association table is then updated accordingly.

Specifically, this matching process allows Coveo to determine whether it should create, update, or delete resources to apply your snapshot.

Resource is listed in the snapshot Resource has an association with the destination organization ID Snapshot application result
Yes No The resource from the snapshot has never been imported in the destination organization. Coveo creates this resource.
Yes Yes The resource in the destination organization is updated to match the configuration provided in the snapshot.
No Yes The resource remains untouched, unless you delete it via the API1
1. Upcoming releases will improve the management of deleted resources.

For Further Information

Refer to the Manage Resource Snapshots section of the Manage an Organization Coveo documentation for more details about the feature, like organization privileges required to perform snapshot-related actions and guidance in automating a resource deployment process.

What's Next for Me?