Migrate changes between cloud organizations

This is for:

In this article

Types of resources you can include in a snapshot
Create and apply resource snapshots
Resource snapshots creation and application under the hood
For further information

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 Platform 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 (for example, query pipelines, indexing pipeline extensions (IPEs), hosted search pages, Coveo Machine Learning (Coveo ML) models).

Note

Not all resource types can be included in a snapshot yet, although the current offer should cover multiple use cases. See Supported resources for a list of the resource types that the snapshot feature supports.

If you would like to include additional resource types in a snapshot, contact your Coveo representative. We will consider further expanding the snapshot feature depending on the demand.

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.

Create and apply resource snapshots

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

1. Create 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:

On the Resource Snapshots (platform-ca | platform-eu | platform-au) page, click Create Snapshot, and then select Of your organization.
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.
Select the resources to include in your snapshot. If you want to index only some resources, specify the desired resources.
Enter a descriptive name for your snapshot. This description will appear on the Resource Snapshots (platform-ca | platform-eu | platform-au) page.
Click Create snapshot or, alternatively, click Save for CLI to download your selection for usage in Coveo CLI.

Note

If you would like to include additional resource types in a snapshot, contact your Coveo representative. We will consider further expanding the snapshot feature depending on the demand.

2. Export the snapshot

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

On the Resource Snapshots (platform-ca | platform-eu | platform-au) page, click the desired snapshot, and then click Export in the Action bar.
In the Export Snapshot panel that opens, select a destination organization.
Enter a descriptive name for your snapshot. This description will appear on the Resource Snapshots (platform-ca | platform-eu | platform-au) page of the destination organization.
Click Export.

3. Apply the snapshot

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

On the Resource Snapshots (platform-ca | platform-eu | platform-au) page, select the desired snapshot, and then click Apply in the Action bar.
The subpage that appears shows whether the prerequisites are met.
- Coveo first checks whether it has all the information it needs. Some sensitive pieces of information may be needed to create or update your resources properly (for example, source credentials). In such case, authorize Coveo to import them from the origin organization, or click Provide via our API to create them manually.
- Next, Coveo checks whether you have the privileges required to edit all resources in the snapshot, as they are required to apply the snapshot. If you don’t have all of these privileges, contact your Coveo administrator.
Once all prerequisites are met, click Continue to snapshot validation. Coveo will check whether your snapshot is valid and can be applied smoothly.
Once the validation process is complete, you can review a diff of the changes to apply. Should errors be detected in some resources, you may want to review them as well, and perhaps modify your snapshot or organization resources to fix them.
Once all errors are fixed, click Continue to apply snapshot, and then, in the dialog, confirm that you want to apply the snapshot.

Note

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

Resource snapshots creation and application under the hood

A 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 (for example, 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, that is, two versions of the same resource.

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

Note

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

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 table of analogous resources 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 is analogous to a resource 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 in the destination organization remains untouched, unless you delete it via the API.

Resource is listed in the snapshot

Resource is analogous to a resource with the destination organization ID

Snapshot application result

Yes

The resource from the snapshot has never been imported in the destination organization. Coveo creates this resource.

Yes

The resource in the destination organization is updated to match the configuration provided in the snapshot.

Yes

The resource in the destination organization remains untouched, unless you delete it via the API.

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.