How to Add New Items to Your XM Cloud Serialization

The Basics of Sitecore Serialization

Sitecore serialization is something you might already know a little about; it plays an important part in managing and transferring content and configuration data within your Sitecore instance. Essentially, it allows you to capture any changes that you make on your local machine and synchronize them with other developers, or staging, QA, and production environments.

There are two main ways to serialize your Sitecore changes: Manual and Automatic. I'm going to cover the basics of both and show you how to add new items to be included in your Sitecore serialization.

Including and Excluding Content Items

Creating a New Content Serialization Module

When you instantiate a new Sitecore instance, Sitecore only adds the bare-bones default items to the serialization list. This means that some of your changes might not get serialized when you run your serialization commands.

It's actually a super simple process to add a new Sitecore item to the serialization list. If you look inside your Sitecore solution folder, you should notice a sitecore.json file. This is the configuration file that contains several properties, including a module's property. This property is what's used to reference created Content Serialization Modules.

The idea behind these Content Serialization Modules is to allow developers to organize your serialization items into designated files. This can help reduce technical debt and all you to easily add/remove items from serialization.

To create a new Serialization Module, first ensure that your sitecore.json has the following reference code inside it. It tells Sitecore that all .module.json files under the src folder are Content Serialization Modules. This way, Sitecore can reference them when deciding which items it should pull or push.

Alternatively, you could add the path directly to your module inside your sitecore.json instead of including the wildcard below.

{
 "modules": [ "src/*/*.module.json" ]
}

After ensuring your sitecore.json file has the above code, we can create our first Serialization Module. I recommend splitting out your serialization items into distinct files. Some examples of modules you could create are:

• Content.module.json
• Core.module.json
• Layout.module.json
• Media.module.json
• System.module.json
• Templates.module.json

To create a module, you must have the following properties:

{
  "namespace": "", //Mandatory - module namespace
  "references": [""], //Optional - References to other modules (they must be deserialized first)
  "items": "" //Optional -  Paths to Items you want serialized.
}

Add New “Items”:

To add a new item to our serialization, we can define an includes array that is an array of objects, with each object being a new item we want to add to our serialization. Each object has a collection of fields to help you fine tune your module. Here is an example of what you include might look like:

"items": {
  "includes": [
    {
      "name": "", 
      "path": "",  
      "rules": [
        {
           "path": "",  //Required
           "scope": "", //Required
           "allowedPushOperations": "" //Optional
        },
        {
           "path": "",
           "scope": ""
        }
      ]
    }
  ]
}

Here we can define the name and path for the item. Then we can use rules to tell Sitecore to return the first match it can find that “matches” our defined rule.

Similar to a C# FirstOrDefault linq query.

Scope:

Allowed Push Operations:

For example, if I am creating a Templates.module.json I would set the namespace to “Templates” and pass in an array of items that I would want to include in my serialization.

{
  "namespace": "Templates",
  "items": {
    "includes": [
      {
        "name": "$Templates/$Foundation",
        "path": "/sitecore/templates/Foundation",
        "allowedPushOperations": "createUpdateAndDelete",
        "scope": "ItemAndDescendants",
        "rules": [
          {
            "path": "/Home",
            "scope": "ItemAndDescendants",
            "allowedPushOperations": "createUpdateAndDelete"
          },
          {
            "path": "/*",
            "scope": "ignored"
          }
        ]
      },
    ]
  }
}

Manual Serialization (In a Nutshell)

Manual Sitecore serialization is the pushing and pulling your content items to/from your Sitecore instance on demand, without relying on automated scheduling or triggers. This is generally used my most developers wince it provides you with more control over when content changes are synchronized between different environments or when specific content updates need to be applied.

You can use the following commands to serialize your Sitecore instance:

sitecore ser pull → This pulls your new local changes into the new .yml files that you can push up to your repo. (Saves your changes)

sitecore ser push → This looks at all the current .yml files in your local repo and pushes those to your current local database. This overrides all your un-pulled changes. (Deletes any unsaved changes)

Notes:

• Its important to note that serializing in Sitecore is backwards from the normal git push/pull operations.
• You may need to download and install the .net runtime on your local system, and run the above commands with the dotnet prefix. Ex: dotnet sitecore ser pull . You can learn how to install the Sitecore cli here.

Useful Sitecore CLI commands:

Automatic Serialization

Automatic Sitecore serialization is simply tracking the changes made in your Sitecore content management system and automatically serializing and synchronizing them. You can easily configure this using the Sitecore command-line interfaces (CLI) and the Sitecore Serialization Versioning System (SVS). The watch command tells the system to continuously look for changes in the specified Sitecore items; then when a change occurs (like updating a template) the corresponding items will be magically pulled from Sitecore and saved to the disk.

If this is something you want to do, the process is super simple and easy to do. Just run dotnet sitecore ser watch in your powershell instance.

If you want to learn more about the watch command, you can take a look at the Sitecore documentation.

Wrapping Up Sitecore Serialization

Adding items to your Sitecore serialization is super simple and easy, hopefully this guide has helped you understand how to create a new content serialization module, and add new items to your Sitecore Serialization.