Sitecore content migration part 2: Converting content

Welcome to the third and last blog in the Sitecore content migration series. In this edition, we’ll explore automating the migration of content, focusing on how to handle template ID and layout changes. Automating content migration, including layouts, can save a significant amount of time. However, it’s important to understand the complexity of Sitecore’s layout features, which include devices, datasource queries, dynamic placeholders, personalization, multivariate testing, shared and final layout. Additionally, complexities like language fallback, clones, and workflows must also be considered for items.

Setting your goals too high can be counterproductive. If your new site is not an exact copy of the original, fully automating the migration of content and layout will require substantial effort. While copying content is straightforward, achieving perfect layout accuracy can be challenging and may still involve manual work if the content and layout are not standardized.

This blog mainly covers migrating from Sitecore MVC to Sitecore SXA Headless, where optimizing the website for SXA Headless and Sitecore Pages will require changes to the layout data.

Content migration options

The options for migrating content are similar to those for migrating media, as discussed in Part 1: Media Analysis. Here are some migration options:

• XM to XM Cloud migration tool: This tool doesn’t support containers or scripting, requiring manual content selection. For Sitecore 10.1+, it can also migrate users. Template ID or layout changes should be handled separately using tools like Sitecore PowerShell. This is useful for "lift and shift" scenarios.
• Sitecore item serialization with CLI: A fast, configuration-based method with rule customization (see Part 2 of this series). Similar to the XM Cloud Migration Tool, template ID or layout changes should be done in a separate step.
• Sitecore authoring and management GraphQL API: This option doesn’t retain the original GUID, but it's highly flexible for scripting, making it a powerful tool for modifying content and layouts during migration.
• Packaging: Suitable for small amounts of content, with similar advantages and disadvantages as CLI.
• Sitecore RESTful API for the ItemService: Easy to use but outpaced by the new GraphQL API, still usable when dealing with older Sitecore versions.

Combining options

You can combine these methods: use APIs for pages and components, and CLI or packaging for data types that remain unchanged, like SXA tags and media. The main drawback of the API is its inability to preserve Item GUIDs, which means extra work to convert references. You could also use the XM to XM Cloud Migration Tool if it suits your needs.

The big advantage of APIs is the flexibility they provide in changing template IDs, field names, and paths, allowing you to restructure the entire content tree if necessary. Changing a path with the CLI can be easily performed by moving it after import. But it can become cumbersome for incremental or repeatable migrations.

The Sitecore Authoring and Management GraphQL API is an excellent choice for migrations that involve more than just copying items with identical templates. For converting a Sitecore MVC site to a headless SXA site, the API is a solid option.

Which API to use for the source Sitecore?

For API-based migration, you have three options. If your source is Sitecore 10.3, the GraphQL Authoring and Management API is ideal, as it supports mutations. For simple data reading, the GraphQL Delivery API is a better fit, though it requires JSS server components. Alternatively, the RESTful API for the ItemService comes out-of-the-box for Sitecore 7.5+ and is a good option if JSS components are not installed.

Migration with RESTful and GraphQL APIs

Migrating a content tree is as simple as iterating through the source tree recursively, fetching each item, and mapping its fields to the target format. Since you control the migration in code, you can easily change template IDs and map fields with complex rules. For an example of this in C#, check out Sitecore Commander. Using .NET for migration scripts offers the advantage of integrating with the Sitecore API to parse layout details and leverage Visual Studio’s powerful debugging tools.

Migrating layouts

For layout migration, extract the __FinalRendering or __Rendering field and parse the XML data. You can use the Sitecore.Kernel for this, like:

using Sitecore.Layouts;

var details = LayoutDefinition.Parse(renderings);

var device = details.GetDevice("{FE5D7FDF-89C0-4D99-9AA3-B5FBD009C9F3}"); // Default device

if (device.Renderings != null)
{
foreach (RenderingDefinition rendering in device.Renderings)
{
// Convert rendering
}
}

Each rendering has a s:id property in its DynamicProperties or ItemID, which is the GUID of the component (e.g., video, slider, or text). The s:ds property represents the datasource, which can be a GUID or a query like query:$site. Additional properties include s:ph (placeholder), s:par (rendering parameters), and others for personalization, testing, etc.

In my case, I created specific conversion logic for each supported component, including rules for datasource conversion. The advantage of only creating datasource items that you come across in the layout of pages you migrate is that you only migrate datasource items that are actually in use, reducing unnecessary data transfer. Because API-created items receive new IDs, you will need to update the layout data accordingly with these new datasource IDs

Multilanguage considerations

There are notable differences between how the RESTful API and GraphQL API handle multilingual content. The RESTful API returns a successful response for an existing item even if it’s not available in the requested language, providing empty values for non-shared fields. On the other hand, the Edge GraphQL API treats the item as "not found" in such cases. However, the Authoring GraphQL API will return the item, even if it doesn’t exist in the specified language.

Wrapping up content migration: A smooth path ahead

Thank you for following along with this final part of our Sitecore content migration series. In this blog, we explored how to automate the migration of complex content and layouts, highlighting various tools and APIs. I hope the insights provided help you streamline your migration process and tackle challenges like template ID and layout changes with ease. Don’t forget to revisit Part 1: Media Analysis and Part 2: Media Migration to build a comprehensive approach to your Sitecore XM Cloud transition.

Stay tuned for more advanced topics in the future!