Today I want to dive into an important piece when migrating to XM Cloud: transitioning from a traditional TDS (Team Development for Sitecore) project 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 TDS project to SCS.
Why Migrate from TDS to SCS?
First things first, let's address the "why" behind making this transition. While TDS has been a trusted companion for many developers over the years, there are some reasons to make a move to SCS:
- Performance: SCS is designed with performance in mind. It works natively with the Sitecore item provider and is optimized for speed, reducing the time it takes to sync items during development. Ongoing performance improvements are being done with SCS to make this even faster.
- 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 does not support TDS. If you want to migrate to XM Cloud, you should convert to SCS.
If you are not planning to migrate to XM Cloud now or in the future, then TDS might still be the right choice for you. This article assumes that you have already made that choice to convert to SCS and walks through the steps.
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 TDS project to SCS. Here's a step-by-step guide to help you make a smooth transition:
Step 1: Evaluate Your Existing TDS Project
Before you begin the migration, first assess your existing TDS project. Understand the scope of your project, the templates, and items you need to migrate, and any custom configurations that are in place.
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:
Step 3: Create an SCS-Compatible Serialization Folder
In your project, you will want to create a dedicated folder structure to store serialized content for SCS. SCS uses YAML files for serialization, so this folder will hold YAML files representing your Sitecore items.
Step 4: Convert your TDS project definition to SCS
There are a few tools that can help take your existing definitions and start converting them to SCS configuration files. In general, a TDS project and an SVS configuration have some similar concepts regarding serialization configuration:
| TDS | SCS | Description |
|---|---|---|
| NeverDeploy | ignored | TDS serialization contains items that should not be deployed but exist to keep hierarchy relations. |
| SVS ignores the routes instead. | ||
| DeployOnce | CreateOnly | This setting ensures a content item is only created if it does not exist. Existing items are not overwritten. |
| AlwaysUpdate | CreateUpdateAndDelete | This setting ensures a content item will always be changed, regardless of the state in the target system. |
| NoChildSynchronization | SingleItem | This setting ensures that only the content item specified is updated. None of the items that have it as a parent will be affected. |
| KeepAllChildrenSynchronized | ItemAndDescendants | This setting forces the item and ALL children and sub-children through the item tree to be affected. |
| KeepDirectDescendantsSynchronized | ItemAndChildren | This setting will force the update across the item and the immediate children but will not change content items further down the content tree. |
I found a few community tools that can parse through the TDS project definitions and generate SCS configuration JSON files by using this mapping.
Get SCS Paths from TDS Project
A PowerShell script by Sitecore MVP Aaron Bickle to generate SCS JSON files. Does not support role migration.
Sitecore TDS to SCS Serialization Converter
A .NET application by Sitecore Solution Architect Joseph Long that you can configure to parse through TDS projects and generate SCS JSON files. Supports role migration but does not migrate role inheritance.
These tools may not cover every single use case. You will likely need to extend them to your needs. You should also note that these convert the project configurations, but they do not deploy content during this step. You will do this in the next step.
You could also do this manually, but I would recommend using a tool to get started so you have less work to do overall.
Step 5: 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 TDS projects 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 validatecommand 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 explaincommand, you can get detailed information on why certain paths are included in the sync. See the docs on the explain subcommand.
Step 6: Update Your Deployment Pipeline
With your content serialization configurations finished, 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 7: 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:
Adding new content that should be deployed
Adding new content that should NOT be deployed
Making a change to content that should override the target version
Making a change to content that should NOT override the target version
Deleting a piece of content from all environments
Wrapping it up!
Migrating from TDS to Sitecore Content Serialization (SCS) can be a manual process, but there are 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!
Top comments (0)