Serialization in Sitecore XM Cloud

Sitecore XM Cloud brings unparalleled flexibility and scalability to managing content-driven applications. A key feature enabling smooth collaboration and streamlined deployment workflows in Sitecore XM Cloud is serialization. Serialization allows developers to manage Sitecore items as files, making it easier to store, version, and deploy content-related configurations.

What is Serialization in Sitecore XM Cloud?

Serialization is the process of converting Sitecore items into a file-based representation, typically YAML, that can be stored in a source control system such as Git. In Sitecore XM Cloud, serialization is primarily handled using the Sitecore Content Serialization (SCS) framework and the Sitecore CLI.

Why Use Serialization?

Serialization offers several key benefits:

Version Control: Track changes to content and configurations in your version control system.
Collaboration: Enable multiple developers to work on the same project without overwriting changes.
Consistency: Ensure the same content and configurations are deployed across all environments (e.g., development, staging, production).
Automation: Simplify deployments by integrating serialized files into CI/CD pipelines.

Key Components of Sitecore XM Cloud Serialization

The sitecore.json file

For configuring serialization of the content items (templates, renderings, settings, etc..) in Sitecore XM Cloud, sitecore.json, found at the root of the repository, plays an important role. This is the file where we specify the paths for the different serialization modules that will be created. Following Helix architecture (even though it is not mandatory to follow Helix principles in Headless and XM Cloud Projects), we will generally have a configuration like below:

"modules": [
    "src/serialization/Foundation/*/*.module.json",
    "src/serialization/Feature/*/*.module.json",
    "src/serialization/Project/*/*.module.json"
  ]

As the paths are dynamic, all the files under Foundation, Feature or Project folder and with the file names ending with “.module.json“ are tracked for serialization.

In the sitecore.json file, configurations related to content serialization like defaultMaxRelativeItemPathLength (to specify maximum allowed serialized item path length) or defaultModuleRelativeSerializationPath (to specify the folders under which the serialized items gets created to provide better structure) can be included. Here we could even configure fields of items that we don’t want to track, such as default Sitecore Standard fields like __Updated, __Created, through the excludedFields property.

"serialization": {
    "defaultMaxRelativeItemPathLength": 120,
    "defaultModuleRelativeSerializationPath": "items",
    "excludedFields": [      
      {
        "fieldId": "d9cf14b1-fa16-4ba6-9288-e8a174d4d522",
        "description": "__Updated"
      },      
      {
        "fieldId": "25bed78c-4957-4165-998a-ca1b52f67497",
        "description": "__Created"
      },      
      {
        "fieldId": "{001DD393-96C5-490B-924A-B0F25CD9EFD8}",
        "description": "__Lock"
      }
    ]
  }

The sitecore.json also contains plugins property where all the plugins installed for the current project are listed. This list gets updated when new plugins are installed, removed or upgraded to a higher version. For Serialization to work using Sitecore CLI, it is mandatory that Sitecore.DevEx.Extensibility.Serialization is listed as one of the plugins.

"plugins": [
    "Sitecore.DevEx.Extensibility.Serialization@5.2.113",
    "Sitecore.DevEx.Extensibility.Publishing@5.2.113",
    "Sitecore.DevEx.Extensibility.Indexing@5.2.113",
    "Sitecore.DevEx.Extensibility.ResourcePackage@5.2.113",
    "Sitecore.DevEx.Extensibility.XMCloud@1.1.110"
  ]

**Creating modules in *.module.json**

Creating a content serialization module to track Sitecore XM Cloud items is fairly easy. Based on the item path in Sitecore, a .module.json file could be created under either Foundation, Feature or Project folder in the repository. The name and path properties are mandatory in the module json file while other properties like scope, database have default values and can be omitted. The scope property specifies if the item alone would be serialized or if it’s children or descendants are also going to be serialized whereas allowedPushOperations property controls if the item can be only created, or modified or deleted too as part of content serialization. The details of properties along with the valid and default values can be found here: https://doc.sitecore.com/xmc/en/developers/xm-cloud/sitecore-content-serialization-configuration-reference.html

This is how a module.json file will look like for a Feature Blog component:

{
  "namespace": "Blog",
  "path": "",
  "items": {
    "includes": [
      {
        "name": "Settings",
        "path": "/sitecore/system/Settings/Feature/Blog",
        "scope": "ItemAndDescendants"
      },
      {
        "name": "Templates",
        "path": "/sitecore/templates/Feature/Blog",
        "scope": "ItemAndDescendants"
      },      
      {
        "name": "Renderings",
        "path": "/sitecore/layout/Renderings/Feature/Blog",
        "scope": "ItemAndDescendants"
      }
    ]
  }
}

Custom Roles and xmcloud.build.json

Serialization of Sitecore custom users and roles in XM Cloud is slightly different to content serialization. For content items, Sitecore uses Items as Resources (IAR), sitecore.json file is the reference file and the content items are synced as part of the Build step in the XM Cloud deployment pipeline. Modules for users and roles, on the other hand, are specified in the xmcloud.build.json file and are deployed as part of the Post actions step in the XM Cloud deployment pipeline.

The xmcloud.build.json includes default post deployment actions that can be customized to fit the project needs. It has an actions property, which amongst others, contain the property scsModules. It is here where the user and roles module.json configuration needs to be included so that it can be serialized into the Sitecore XM Cloud instance.

The code snippet below displays the content of a typical xmcloud.build.json file. The modules property in scsModules contains reference to a Foundation.Roles module file where the custom roles have been defined.

"postActions": {
  "actions":{
    "warmUpCm": {
      "urls": []
    },
    "scsModules": {
      "modules": ["Foundation.Roles"]
    },
    "populateSchema": {
      "indexNames": []
    },
    "reindex": {
      "indexNames": []
    },
    "publish": {
      "path": "",
      "languages": [],
      "itemIds": [],
      "targets": [],
      "republish": true,
      "publishSubItems": true
    }
  }
}

{
    "namespace": "Foundation.Roles",
    "tags": [
        "Foundation"
    ],    
    "roles": [      
      {
        "domain": "abc",
        "pattern": "[a-zA-Z0-9]+"
      }      
    ]
}

Putting it together with Sitecore CLI

Once the modules for the content and roles are defined, the next logical step would be to pull the items from the Sitecore instance so that they get serialized in the file system and then push them to the remote Sitecore XM Cloud instance.

The logical sequence of steps are as follows:

Install Sitecore CLI
Connect Sitecore CLI with the local Sitecore XM Cloud instance
Pull items from local Sitecore XM Cloud instance to file system
Connect Sitecore CLI with the remote Sitecore XM Cloud instance
Push serialized Sitecore items to remote Sitecore XM Cloud instance

Install Sitecore CLI

As most of the Sitecore XM Cloud repositories are cloned from the Starter repository from Sitecore, running the command dotnet tool restore in a terminal with administrator privileges should be sufficient. It is also mandatory that .NET 8 is installed as a prerequisite for Sitecore CLI to work.

Connect Sitecore CLI with the local Sitecore XM Cloud instance

Two commands need to be executed:

Login: dotnet sitecore cloud login

This command authenticates against an existing Sitecore XM Cloud instance

Connect: dotnet sitecore connect --ref xmcloud --cm https://xmcloudcm.localhost --allow-write true -n local

This command connects the repository to the locally running Sitecore XM Cloud instance. When running this command for the first time, it can be observed that the .sitecore/user.json file gets updated to include a reference for the local instance.

Pull items from local Sitecore XM Cloud instance to file system

dotnet sitecore ser pull -n "local" command needs to be executed to pull Sitecore items from the running local instance into the file system. Please note only those items are pulled for which there is a path described in the *.module.json files.

Connect Sitecore CLI with the remote Sitecore XM Cloud instance

Connect: dotnet sitecore cloud environment connect -id <environment-id> --allow-write true

Push serialized Sitecore items to remote Sitecore XM Cloud instance

dotnet sitecore ser push -n "dev" is the command used to push the Sitecore items to a dev instance. Please note here dev is the environment name and should be replaced with the environment to which items need to synced to.

Sitecore CLI could be used to do a ton of other stuff too which are described in detail here: https://doc.sitecore.com/xmc/en/developers/xm-cloud/sitecore-command-line-interface-reference.html

Conclusion

Serialization is an essential feature for managing Sitecore XM Cloud projects efficiently. By converting Sitecore items into version-controlled files, you can streamline collaboration, ensure deployment consistency, and simplify environment management.