How to Synchronize Sitecore Content Across XM Cloud Environments Using the CLI

Introduction

Periodic syncing of content across environments is the most common requirement for any Sitecore project. In XM Cloud, we don’t have the option to take a database backup of one environment and restore it on another environment. Using Sitecore CLI is recommended to pull the content from the source environment and push the content to the target environment. This article describes the step-by-step procedure to be followed.

Prerequisites

• .NET 8, Windows PowerShell, and Sitecore CLI installed on your machine

• Organization Admin access to the Deploy App or Organization user access with an admin role to the source and target environments.

Steps

1) Create a new folder called Migration and open that folder in CMD.

2) Run the command dotnet sitecore init.

3) The above command creates the below scaffold in the migration folder.

4) Add the plugin Sitecore.DevEx.Extensibility.XMCloud using the below command.

dotnet sitecore plugin add -n Sitecore.DevEx.Extensibility.XMCloud

5) Run the command Sitecore cloud login, it opens xm cloud login page in browser, once you provide consent you would be authenticated to the Sitecore cloud portal from the cli.

6) In Sitecore.json file update the TODO with Project or a folder Name of your choice, also update any serialization configurations if required.

{
  "$schema": "./.sitecore/schemas/RootConfigurationFile.schema.json",
  "modules": [
    "./Project/*.module.json"
  ],
  "plugins": [
    "Sitecore.DevEx.Extensibility.Serialization@6.0.23",
    "Sitecore.DevEx.Extensibility.Publishing@6.0.23",
    "Sitecore.DevEx.Extensibility.Indexing@6.0.23",
    "Sitecore.DevEx.Extensibility.ResourcePackage@6.0.23",
    "Sitecore.DevEx.Extensibility.Database@6.0.23",
    "Sitecore.DevEx.Extensibility.XMCloud@1.1.73"
  ],
  "serialization": {
    "defaultMaxRelativeItemPathLength": 100,
    "defaultModuleRelativeSerializationPath": "serialization",
    "removeOrphansForRoles": true,
    "removeOrphansForUsers": true,
    "continueOnItemFailure": false,
    "excludedFields": [],
    "progressiveMetadataPull": false
  },
  "settings": {
    "telemetryEnabled": true,
    "cacheAuthenticationToken": true,
    "versionComparisonEnabled": true,
    "apiClientTimeoutInMinutes": 5
  }
}

7) In the Migration Folder, create a folder called Project and add your serialization Module files in the folder. Add the modules and rules as per your synchronization requirement. Below is the sample module file for reference.

{
  "$schema": "../../.sitecore/schemas/ModuleFile.schema.json",
  "namespace": "Content",
  "references": [],
  "items": {
    "includes": [

      {
        "name": "Node1",
        "path": "/sitecore/content/Tenant/site1",
        "scope":"ItemAndDescendants"       
      },
        {
        "name": "Node2",
        "path": "/sitecore/content/Tenant/site2",
        "scope":"ItemAndDescendants"       
      },
      {
        "name": "Media Node",
        "path": "/sitecore/media library/Site/Images",
        "scope":"ItemAndDescendants"       
      }

    ]
  }
}

8) Under .sitecore open the user.json, add the below environments under the endpoints, update host to match your environment host names.

 "my-source-environment": {
      "ref": "XmCloud",
      "allowWrite": true,
      "host": "https://my-source-sitecore-instance-host.sitecorecloud.io/",
      "variables": {}
    },
    "my-target-environment": {
      "ref": "XmCloud",
      "allowWrite": true,
      "host": "https://my-target-sitecore-instance-host.sitecorecloud.io/",
      "variables": {}
    }

9) your updated user.json should look as per the below hierarchy.

10) if you are an organization admin and don’t want to add the environments manually in the user.json file you can run the below commands.

dotnet sitecore cloud project list #lists down the projects
#take a note of project id and use in the below command
dotnet sitecore cloud environment list --project-id <your-project-id> 
#take a note of the environment id's and run the below command to connect to your environments
dotnet sitecore cloud environment connect -id <your-env-id> --allow-write true

11) Run the below command to pull the content from the Source environment, -i parameter is used to define the namespace of the module that you want to pull -n parameter is used to specify the environment name.

sitecore ser pull -i content -n my-source-environment

12) After the above command runs successfully, you should see the yml files of the items that match the rules specified in the module file under the serialization folder.

13) Run the below command to push the content to your target environment.

sitecore ser push -i content -n my-source-environment

14) With the above steps you should be able to pull the content from source environment and push to the Target Environment.

Important Notes

1) Creation of serialization Module file is important for this synchronization. make sure that you have added the proper rules in the module file.

2) Divide into multiple small modules to prevent timeout issues while pulling and pushing the content.

3) Make sure to exclude the environment specific items that should not be synchronized across the environments.

4) Serialization would fail if duplicate paths are found, make sure to rename the items if there are any duplicate paths.

5) Push operation would fail if any of the templates doesn’t exist in the target instance, make sure templates are synchronized before content synchronization.

6) There are no serialization logs available in the target sitecore instance so it would be always a good practice to take a backup of the target environment in a different folder which you can use if you want to restore the previous content.

7) You can use the same approach to synchronize to your local environment as well.

Conclusion

Sitecore CLI simplifies content synchronization process, using the above steps we can seamlessly transfer content across environments