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
- Part 1: Scope Planning
- Part 2: Upgrade Tactics
- Part 3: Content Migration
- Part 4: Upgrading the Codebase
- Part 5: Changes in Sitecore 10.x
- Part 6: Testing and Going Live
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
Depending 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
Sitecore 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.- Free-to-use an open-source tool
- Uses Unicorn and Rainbow serialization
- Multithreaded operation is very fast!
- Both servers require Content Migrator installed
Razl
Offers 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
We’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.- 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 "https://old.site"
$destinationSession = New-ScriptSession -user "admin" -pass 'b' -conn "https://new.site"
$copyProps = @{
"WhatIf"=$true
"CopyBehavior"="CompareRevision"
"Recurse"=$true
"RemoveNotInSource"=$false
"ClearAllCaches"=$true
"LogLevel"="Detailed"
"CheckDependencies"=$false
"BoringMode"=$false
"FailOnError"=$false
}
$copyProps["SourceSession"] = $sourceSession
$copyProps["DestinationSession"] = $destinationSession
# Default Home Item
Copy-RainbowContent @copyProps -RootId "{110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9}"
Data Exchange Framework
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.
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
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.
Serialization
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?
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:
aspnet_Membership aspnet_Profile aspnet_Roles aspnet_Users aspnet_UsersInRoles RolesInRoles
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:
main_9d32dee9-17fd-4478-840b-06bab02dba6c
to the new format, so it becomes:
main-{9d32dee9-17fd-4478-840b-06bab02dba6c}-0
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.
