Converting a Unicorn project to Sitecore Content Serialization (SCS)

Today I want to cover an important piece when migrating to XM Cloud: transitioning Unicorn serialization formats to the new Sitecore Content Serialization (SCS) format. In this article, I'll walk you through some of the reasons for the switch, but mostly focus on the tools and process for migrating your Unicorn configurations to SCS.   

I want to throw a big shout-out to the Unicorn community that helped me with this article. I haven't used Unicorn before and I had to lean on a lot of smart folks to gather the information together. Thanks to Mark Cassidy, Kamruz Jaman, Michael West, Richard Seal, Justin Laster, Dylan Young, Mihaly Arvai, Martin Miles, and probably others that I forgot!

Why migrate from Unicorn to SCS? 

First things first, let's address the "why" behind making this transition. While Unicorn is an excellent choice for serialization on Sitecore XM or Sitecore XP solutions, there are some reasons to make a move to SCS: 

• Future-Proofing: As Sitecore continues to evolve, it's clear that SCS is the direction that Sitecore is heading in. By transitioning to SCS now, you're ensuring your development workflow is aligned with the Sitecore roadmap. 
• Migration to XM Cloud: While you have options for serialization tools in self-hosted installations of Sitecore XM/XP, XM Cloud only fully supports SCS flows today. There are ways to keep Unicorn in your flow (which I'll cover next) but XM Cloud is designed for developers using SCS. 

But what if I want to stay on Unicorn with XM Cloud? 

This is absolutely not recommended by Sitecore, and I wouldn't personally recommend it for any customer use cases, but I did figure out a way to use Items as Resources (IAR) and the Sitecore CLI to support Unicorn serialization files, but still deploy to XM Cloud.

👉 Read about deploying Unicorn to XM Cloud with IAR ▶

Should I stay or should I go? 

If you are not planning to migrate to XM Cloud now or in the future, or you are okay with the outlined workaround for using Unicorn with XM Cloud, then Unicorn might still be the right choice for you! The rest of this article assumes that you have already made the choice to convert to SCS and will walk through the steps.  

What are the differences between Unicorn and SCS

Unicorn and SCS are not the same tools, so it's important to know the impact of moving from Unicorn to SCS. What will you will gain as extra capabilities? What things will you no longer have after the migration? While much is similar, in the below table are the unique features of each.

Unicorn features lost when moving to XM Cloud	Sitecore Content Serialization (SCS) features you gain
Open Source project strongly supported by the community	Supported by Sitecore Support
Supports database specified at an individual file level	Create Items as Resources (IAR) packages
Real-time transparent syncs (similar to SCS 'watch' but more immediate)	Can connect to multiple environments from same system
	Easily integrate as part of DevOps CI/CD
	Visual Studio plugin available (licensing required)

The Conversion Journey: A step-by-step migration guide 

Now that we understand the "why", let's go through a sample plan for migrating your Unicorn configs to SCS. Here's a step-by-step guide to help you make a smooth transition: 

Step 1: Evaluate Your Existing Unicorn Project 

Before you begin the migration, take a good look at your existing Unicorn project. Familiarize yourself with the folder structure, configurations, and the types of items being serialized. This knowledge will come in handy as you plan your SCS migration. 

This is also a good time to identify any irrelevant or inconsistent serialization configurations. Over time, items may have been added into serialization that are either no longer required or should no longer be managed through source control. 

Very important: Make sure to check which default Sitecore items are overridden! In some projects, there are custom security settings or other changes applied to areas of the content tree that are normally shipped with the product. These are often overlooked when migrating to SCS.

A caveat about XM Cloud: The content items shipped with XM Cloud are delivered using Items as Resources (IAR). Depending on your sync choices, your configuration could prevent updates from the Sitecore XM Cloud team from being deployed. Content in the database (i.e. your sync'd items) will override those IAR values. Examine your overrides to make sure they are absolutely necessary. 

Step 2: Install SCS and Prerequisites 

Ensure that your local Sitecore development environment is compatible with Sitecore Content Serialization (SCS) and ready to push to Sitecore XM Cloud. Install the necessary Sitecore modules and SCS-related tools.  

Read about the requirements in the docs:  

• Install the Sitecore CLI 
• Install Sitecore for Visual Studio 

Step 3: Convert Unicorn configs to SCS 

There are a few tools that can help take your existing Unicorn configs and start converting them to SCS configuration files. The Unicorn and SCS configurations are quite similar, so the example scripts tend to find your serialization.config files and then convert them to the equivalent JSON module file.

A sample Unicorn config file

 

<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/">
  <sitecore>
    <unicorn>
      <configurations>
        <configuration
          name="Project.HelixBase"
          description="HelixBase site content"
          dependencies="Foundation.*,Feature.*,Project.Common"
          patch:after="configuration[@name='Foundation.Serialization']"
          extends="Helix.Feature.Base">
          <predicate>
            <include name="Project.HelixBase.Templates" database="master" path="/sitecore/templates/Project/HelixBase" />
            <include name="Project.HelixBase.Renderings" database="master" path="/sitecore/layout/renderings/Project/HelixBase" />
            <include name="Project.HelixBase.Layouts" database="master" path="/sitecore/layout/layouts/Project/HelixBase" />
            <include name="Project.HelixBase.PlaceholderSettings" database="master" path="/sitecore/layout/placeholder settings/Project/HelixBase" />
            <include name="Project.HelixBase.Models" database="master" path="/sitecore/layout/models/Project/HelixBase" />
            <include name="Project.HelixBase.Content" database="master" path="/sitecore/content/HelixBase"/>
            <include name="Project.HelixBase.Media" database="master" path="/sitecore/media library/Project/HelixBase">
              <exclude children="true"/>
            </include>

          </predicate>
        </configuration>
      </configurations>
    </unicorn>
  </sitecore>
</configuration>

(Example Serialization.config from Mihaly Arvai: https://gist.github.com/Mitya88/5c9e29b9d04f1eff42700568f5bd8541/)

After converting to SCS 

{
    "namespace":  "Project.HelixBase",
    "references":  [
                       "Foundation.*",
                       "Feature.*",
                       "Project.Common"
                   ],
    "items":  {
                  "includes":  [
                                   {
                                       "name":  "Project.HelixBase.Templates",
                                       "path":  "/sitecore/templates/Project/HelixBase",
                                       "database":  "master"
                                   },
                                   {
                                       "name":  "Project.HelixBase.Renderings",
                                       "path":  "/sitecore/layout/renderings/Project/HelixBase",
                                       "database":  "master"
                                   },
                                   {
                                       "name":  "Project.HelixBase.Layouts",
                                       "path":  "/sitecore/layout/layouts/Project/HelixBase",
                                       "database":  "master"
                                   },
                                   {
                                       "name":  "Project.HelixBase.PlaceholderSettings",
                                       "path":  "/sitecore/layout/placeholder settings/Project/HelixBase",
                                       "database":  "master"
                                   },
                                   {
                                       "name":  "Project.HelixBase.Models",
                                       "path":  "/sitecore/layout/models/Project/HelixBase",
                                       "database":  "master"
                                   },
                                   {
                                       "name":  "Project.HelixBase.Content",
                                       "path":  "/sitecore/content/HelixBase",
                                       "database":  "master"
                                   },
                                   {
                                       "name":  "Project.HelixBase.Media",
                                       "path":  "/sitecore/media library/Project/HelixBase",
                                       "database":  "master",
                                       "scope":  "SingleItem"
                                   }
                               ]
              }
}

(Example module.json from Mihaly Arvai: https://gist.github.com/Mitya88/38b508019016e6998972350d8f3aaedd)

NOTE: The above code samples are directly from the article by Mihaly Arvai (linked below).

Check out these community scripts that you can extend for your needs to convert your Unicorn to SCS! 

• Mihaly Arvai --- Convert Unicorn Serialization configs into Sitecore Content Serialization module JSON with Powershell 
• Martin Miles --- Convert Unicorn to Sitecore CLI serialization 

Step 4: Test and Iterate 

Before you declare victory, you need to thoroughly test your new SCS configs to ensure that all serialized content is being correctly deployed and pulled against your local instance. Verify that the items, templates, and configurations work as expected. 

This is where you may need to adjust the logic or configurations used to convert your Unicorn configurations if you are not seeing the results you expect.

There are a few tools you can use to start checking your serialization configs: 

Run a validation of your config\
The sitecore ser validate command can be used to look for any problems in your config. If any are found, you can then run sitecore ser validate --fix to fix common problems. See the docs on validation. 

Get a sync explanation report\
By using the sitecore ser explain command, you can get detailed information on why certain paths are included in the sync. See the docs on the explain subcommand. 

Step 5: Update Your Deployment Pipeline 

With your content serialization configurations finalized, you will now need to update your deployment pipeline for content. This might involve adjusting your local deployment process, continuous integration pipelines, and ensuring all team members are aware of the new workflow. 

Watch this video by Rob Earlam to see how the Sitecore DevRel team converted their CI/CD DevOps flow to work with XM Cloud and the Sitecore CLI:

Step 6: Test Deployments 

With your full flow now updated, you will need to test that your updates through CI/CD pipelines are being sent (or ignored) correctly as you make changes to your content and serialize them into your source control repository. 

Remember to test these scenarios: 

1. Adding new content that should be deployed 
2. Adding new content that should NOT be deployed 
3. Making a change to content that should override the target version 
4. Making a change to content that should NOT override the target version 
5. Deleting a piece of content from all environments 

Wrapping it up! 

Migrating from Unicorn to Sitecore Content Serialization can be a manual process, but there are community tools that can help you get there faster! In either case, it requires careful consideration and planning. By following the steps outlined above, you can transition your project to SCS and start working with XM Cloud!