Skip to main content


Upgrading Sitecore Platforms – Content Migration

Patrick Tomasso Oaqk7qqnh C Unsplash

So, you find yourself in a need of a Sitecore Upgrade and don’t know what to start with or how to approach it? This series of blog posts will cover the whole process from zero to hero, or in upgrade terms – from planning to going live. It comes in the form of a guide that will save you at least 2 times of cumulative effort, due to avoiding hidden traps and unobvious issues on your way to a shiny upgraded solution. Over time I have struggled and documented most of these issues and now want to share them all in one place.


Content migration

When asking my colleagues what was the biggest challenge with their upgrade experience, almost everyone responded – migrating the content.

Content migration is often the most time-consuming and challenging part of upgrading a Sitecore website because it involves moving large amounts of data from the old site to the new one. This can be a complex and delicate process, as the content must be accurately transferred and properly formatted to work with the new Sitecore version. Additionally, the migration process often requires careful planning and coordination with various teams, including content creators, developers, and stakeholders, to ensure that the content is migrated smoothly and without disruptions to the user experience.

1. Content maintenance

Housekeeping SitecoreDepending on your level of ownership, it may be a good idea to undertake content maintenance. This is optional but highly desirable.

Removing legacy item versions is a know good practice to keep less than 10 versions per item improving content editing performance. Once I saw 529 versions of the site’s Home item and doubted the authors did need them all.

You can remove legacy items manually by running the SPE script (PowerShell Extensions script to delete unused media Items older than 30 days ) or perform that on a regular basis by creating a Rule in Rules Engine to automatically keep a number of versions less than the desired number (Rules Engine Actions to Remove Old Versions in the Sitecore).

Consider cleaning up Media Library as it is the most abused area of content, typically. Untrained or simply rushing editors often place content without any care. Almost every single solution I’ve seen had some issues with the media library: either messed up structure, lots of unused and uncertain media, or both. These items are heavyweight and bloat database and content tree without bringing any benefit. There is a PowerShell Extensions script to list all media items that are not linked to other items, so having those you may revise the list and get rid of those unwanted ones.

You may also want to clean up broken links prior to doing an upgrade. Sitecore has an admin page that allows removing broken links. You can find it in the Admin folder: RemoveBrokenLinks.aspx – just select the database and execute the action.

From 9.1 default Helix folders comes OOB with databases so became universal. At the same time, plenty of Helix solutions were implemented before and their corresponding folders IDs do not match those coming OOB in later versions.

For example, the existing solution also has folders like /sitecore/Layout/Renderings/Feature but they are not coming out of the box and therefore serialized, but what is even worse – having different IDs from those coming OOB that are now universal.

You’ll need to rework serialization to match the correct parent folders coming from OOB.

2. Content migration options

In fact, you’ve got plenty of options to migrate the content. Let’s take a look at what they are.

Sitecore Packaging

This is the default way of occasional exchanging items between instances known to every developer. However, it is extremely slow and does not work well with large packages of a few hundred megabytes.

Sidekick Content Migrator

Sidekick Content MigratorSitecore Sidekick is a free-to-use tool and has a Content Migrator module using Rainbow serialization format to copy items between instances in a multi-threaded way. Unlike packages it super-fast. Keep in mind that both servers need to have the content migrator installed on them.
Features and advantages:
  • Free-to-use an open-source tool
  • Uses Unicorn and Rainbow serialization
  • Multithreaded operation is very fast!
  • Both servers require Content Migrator installed
Download Sitecore Sidekick (by Jeff Darchuk)


RazlOffers quite an intelligent way of copying items between the servers.

Features and advantages:

  • Visual Database Comparison tool
  • Provides the most intelligent copying toolset
  • It is an official tool from the vendor
  • However, this software is not free and requires a license to run.

Read more about Sitecore Razl – a tool for compare and merge.

Sitecore PowerShell Migration

PowerShell Extension Content MigratorWe’ve got a script to migrate content between Sitecore instances using Sitecore PowerShell Extensions (by Michael West) which also leverages Unicorn and Rainbow serialization. This script is extremely fast, but it requires SPE with Remoting enabled on both instances.
Features and advantages:
  • Migrates content between instances
  • Uses Unicorn and Rainbow serialization
  • Requires SPE Remoting on both instances
  • Works extremely fast!
  • Written by SPE author/maintainer
$sourceSession = New-ScriptSession -user "admin" -pass 'b' -conn ""
$destinationSession = New-ScriptSession -user "admin" -pass 'b' -conn ""

$copyProps = @{

$copyProps["SourceSession"] = $sourceSession
$copyProps["DestinationSession"] = $destinationSession

# Default Home Item
Copy-RainbowContent @copyProps -RootId "{110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9}"

Data Exchange Framework

A heavy-weight alternative to any other migration approach, Data Exchange Framework (DEF) provides organizations with a standardized way to move data from one system to another in an efficient and secure manner. It takes much more time to set up, however once done DEF would be able to perform recurring content pull and update on a regular basis.

Some of the key benefits of using DEF include:
• It provides a consistent, centralized approach to data management, making it easier to manage data from multiple sources.
• It allows developers to create custom data providers and data formats, which makes it possible to integrate DEF with a wide range of external systems.
• It has a user-friendly interface that makes it easy for non-developers to manage data imports and exports.
• It supports a range of data transformation and mapping capabilities, which makes it possible to manipulate data as it is imported or exported.
Overall, DEF can help improve the efficiency and reliability of data management in Sitecore-powered websites and applications. Once set up, it will naturally migrate and processing any content from any API, not just another Sitecore database.

Move an item to another database from Control Panel

If none of the above options work for you, there is a built-in tool to copy items between databases that is part of the Control Panel. The trick is to plug the target database as an external database to an instance so that it becomes seen in Sitecore, then you’ll be able to copy items using this option. It has limited functionality and works reasonably slowly, but allows copying data both ways.

Move Item Into Another Database

Please note: if you are migrating content to version 10.1 or newer, there is a much better way of dealing with a content and database upgrade, which I will explain in detail below.

3. Content Security

There are a few options to transfer Users and Roles from one instance to another.

Sitecore Packages

Sitecore Packages

You can use the standard Package Designer from the Development Tools menu in the Sitecore Desktop. You can then add the Roles and Users that you want to package up for migration, generate the package, download it and then install it at the target instance in the same way you would do for content.



An alternative is to use the Serialization option from within the User Manager and Role Manager applications. The users and roles will be serialized to (data)/serialization/security folder. You can copy this from the source instance to the target instance and then use the revert option.

For both of these options, the user’s password is not transferred and instead reset (to a random value when using Sitecore Packages or to “b” when using serialization).

How to deal with the passwords?

Passwords Are Neither Packaged Nor Serialized

You can then either reset the password for the users manually (from the User Manager), or the users themselves can reset the password by the “forgot your password” option from the login screen, assuming the mail server has been configured and they get password recovery email.

You also have the option to use the admin folder TransferUserPasswords.aspx tool to transfer the passwords from the source and target databases. To do so you will need both connection strings and these connections must have access enabled. Read more about Transferring user passwords between Sitecore instances with TransferUserPasswords.aspx tool.

Raw SQL?

Without having the required access, you could do that manually with SQL. The role and user data are stored using ASP.NET Membership provider in SQL Server tables in the Core database. Please note that Sitecore 9.1 and newer Membership tables could be extracted from Core into their own isolated Security database (read this article about extracting Sitecore membership data away from Core DB into an isolated Security database).

So it is possible to transfer the roles and users with a tool such as Redgate SQL. You will need to ensure you migrate user data from the following tables:


You may adjust and use SQL script to migrate content security when both source and target DBs are on the same SQL server. Also, follow up on a StackExchange answer about Moving users/roles/passwords to a new core database (by Kamruz Jaman).

4. Dynamic placeholders format

From version 9.0 Dynamic Placeholders became an integral part of the platform, unlike previously we used 3-rd party modules. However, Sitecore has implemented its own format for addressing components: {placeholder key}-{rendering unique suffix}-{unique suffix within rendering}.

That means your previous layouts will not be shown on the page unless you update presentation details for these differences otherwise the renderings. For example, if you have a component on a page in an old dynamic placeholder format, you need to change it from:


to the new format, so it becomes:


There are a few solutions how to approach that

  • with PowerShell Extensions script (by Rich Seal)
  • by creating a service (or admin folder page): one, two

Also, you no longer need a 3-rd party implementation module, so remove it (both DLL and its config patch file). Its functionality was “moved” into built-in Sitecore MVC libraries which you of course need to reference from web.config:

<add namespace="Sitecore.Mvc"/>
<add namespace="Sitecore.Mvc.Presentation"/>

Read more: an official guide on dynamic placeholders.

The next post in this series is devoted to upgrading the codebase.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Martin Miles

Martin is a Sitecore Expert and .NET technical solution architect involved in producing enterprise web and mobile applications, with 20 years of overall commercial development experience. Since 2010 working exclusively with Sitecore as a digital platform. With excellent knowledge of XP, XC, and SaaS / Cloud offerings from Sitecore, he participated in more than 20 successful implementations, producing user-friendly and maintainable systems for clients. Martin is a prolific member of the Sitecore community. He is the author and creator of the Sitecore Link project and one of the best tools for automating Sitecore development and maintenance - Sifon. He is also the founder of the Sitecore Discussion Club and, co-organizer of the Los Angeles Sitecore user group, creator of the Sitecore Telegram channel that has brought the best insight from the Sitecore world since late 2017.

More from this Author

Follow Us