Reading time: 7 min read
How to Add New Items to Your XM Cloud Serialization
Adding new serialization items has never been easier
Start typing to search...
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.
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:
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.
}
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:
| Scope Value | What it does |
|---|---|
| SingleItem | Only this item |
| ItemAndChildren | This item and its immediate children. |
| ItemAndDescendants | This item and all its descendants |
| DescendantsOnly | Only the descendants of this item |
| Ignored | All children and descendants will be ignored (excluding any previously matched items) |
Allowed Push Operations:
| Allowed Push Operations Value | What it does |
|---|---|
| CreateOnly | Only serialize new item creations |
| CreateAndUpdate | Serialize new item creations and updates to that item |
| CreateUpdateAndDelete | Serialize new item creations, updates and deletes to that item |
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 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:
dotnet prefix. Ex: dotnet sitecore ser pull . You can learn how to install the Sitecore cli here.| Command | Description |
|---|---|
| info | Provides information about the solution’s configuration |
| explain | Provides detailed serialization information on a Sitecore item path and optional database |
| pull | Takes items from Sitecore, serializes them, and stores them as .yml files on a given file system path |
| push | Takes items serialized as .yml files on disk and pushes them to a destination Sitecore instance. |
| diff | Compares serialization items between a source Sitecore instance and a destination Sitecore instance. |
| validate | Ensures file system integrity of serialized items and paths |
| package | You can use this to gain more information about package operations like package create and package install |
| watch | Monitors changes to content items in a Sitecore instance and automatically serializes the changes to your file system. |
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.
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.