Upgrading From Kentico Xperience 13 To Xperience By Kentico.

 Manthan Jangid 
 Jan 17, 2024 

A Smooth transition with the Migration Toolkit.

In this document, we will learn how to upgrade our Xperience 13 website to Xperience by Kentico.

Source:

So, your Kentico Xperience 13 instance needs to be rocking at least Refresh 5 (hotfix 13.0.64) or newer. No worries about your development model (Core or MVC 5), we're embracing both! Just make sure your source instance's database and file system are within arm's reach when you're running the Migration Toolkit. It's like a digital treasure hunt! 🗺️
 

Target: 

The Migration Toolkit is our trusty sidekick, regularly updated and high fiving the latest Xperience by Kentico version (currently grooving at 28.0.1). Your target instance's database should be an empty canvas, ready for a clean slate—no drama, just good vibes! ✨
 

Supported Data and Limitations 🚀🛑: 

Xperience by Kentico is like a superhero with a focused set of powers. The Migration Toolkit is here to save the day, but not everything from Xperience 13 can make the jump. Brace yourself for a bit of manual migration action!

• Sites: Each site transforms into a cool website channel object. Superhero transformation activated! 🦸‍♂️
• Cultures: Mapping the cultural journey to language in the Languages application. It's like teaching languages to your website—Bonjour, Hola, Hello! 🌍
• Content Types: The toolkit attempts some magic tricks, mapping page type fields to Xperience by Kentico equivalents. 🪄 Abracadabra!
• Pages: From published to archived, every page finds its place under the right website channel. Linked pages transform into standard page copies—like clones but cooler! 👯‍♂️
• Media Libraries: Where media files find a new home, but permissions take a rain check. No VIP access here! 🚫
• Forms: Migrate those form autoresponders manually, like a pro! 📧 Your forms are getting a DIY makeover!
• Users and Roles: Only the privileged make the cut. And roles, don't forget to configure those permissions post-migration! It's like handing out backstage passes. 🎤

 

Unsupported Data 🚫:

 A few things won't make the journey just yet:

• Contact Groups: Static groups take a break, but dynamic groups can be recreated with a bit of manual love. 💖 It's like giving your contacts a makeover!
• License Keys: Different format, different party. It's like upgrading from a medieval key to a futuristic key card! 🗝️➡️💳

Remember: Macros are cool, but they might not be the life of the party in Xperience by Kentico. 🎉 So, leave the macro drama behind!

Your upgrade journey is about to begin—get ready for an exciting ride to Xperience by Kentico! 🌐✨ And remember, every tech adventure needs a bit of humour! 😄

 

Get started!

Follow these simple steps to effortlessly migrate your data, settings, and more! 🛠️
 

Step 1: Clone or Download the Migration Toolkit Source Code from Here.

Head over to our repository and grab the Migration Toolkit source code. You can either clone it or download it to your machine.
 

Step 2: Open the Solution in Visual Studio.

Fire up Visual Studio and open the Migration.Toolkit.sln solution. This is where the magic happens!
 

Step 3: Configure Options in Migration.Toolkit.CLI/appsettings.json.

Fine-tune your migration process by configuring options in the appsettings.json file. For detailed instructions, check out the below table.
 

Configuration	Description
er-KxConnectionString	The connection string to the source Kentico Xperience 13 database.
KxCmsDirPath	The absolute file system path of the CMS folder in the source Kentico Xperience 13 administration project. Required to migrate media library files.
XbKConnectionString	The connection string to the target Xperience by Kentico database.
XbKDirPath	The absolute file system path of the root of the target Xperience by Kentico project. Required to migrate media library and page attachment files.
XbKApiSettings	Configuration options set for the API when creating migrated objects in the target application. The ConnectionStrings.CMSConnectionStringoption is required - set the connection string to the target Xperience by Kentico database (the same value as XbKConnectionString).
MigrationProtocolPath	The absolute file system path of the location where the migration protocol file is generated. For example: "C:\Logs\Migration.Toolkit.Protocol.log"
MigrateOnlyMediaFileInfo	If set to true, only the database representations of media files are migrated, without the files in the media folder in the project's file system. For example, enable this option if your media library files are mapped to a shared directory or Cloud storage. If false, media files are migrated based on the KxCmsDirPath location.
MemberIncludeUserSystemFields	Determines which system fields from the CMS_User and CMS_UserSettings tables are migrated to CMS_Member in Xperience by Kentico. Fields that do not exist in CMS_Member are automatically created. The sample appsettings.json file included with the toolkit by default includes all user fields that can be migrated from Kentico Xperience 13. Exclude specific fields from the migration by removing them from this configuration option.
UseOmActivityNodeRelationAutofix	Determines how the migration handles references from Contact management activities to non-existing pages. Possible options: DiscardData - faulty references are removed, AttemptFix - references are updated to the IDs of corresponding pages created by the migration, Error - an error is reported and the reference can be translated or otherwise handled manually
UseOmActivitySiteRelationAutofix	Determines how the migration handles site references from Contact management activities. Possible options: DiscardData,AttemptFix,Error
EntityConfigurations	Contains options that allow you to fine-tune the migration of specific object types.
EntityConfigurations.<object table name>.ExcludeCodeNames	Excludes objects with the specified code names from the migration.
OptInFeatures.QuerySourceInstanceApi.Enabled	If true, source instance API discovery is enabled to allow advanced migration of Page Builder content for pages and page templates.
OptInFeatures.QuerySourceInstanceApi.Connections	To use source instance API discovery, you need to add a connection JSON object containing the following values: SourceInstanceUri - the base URI where the source instance's live site application is running. Secret - the secret that you set in the ToolkitApiController.cs file on the source instance.
OptInFeatures.CustomMigration.FieldMigrations	Enables conversion of media selection text fields to media library files. See Convert text fields with media links to media libraries for more information.

 

Source: github(Kentico)

Step 4: Rebuild and Restore.

Hit that rebuild button and make sure all the required NuGet packages are restored. We want everything in tip-top shape!

Step 5: Open the Command Line Prompt.

Navigate to the output directory of the Migration.Toolkit.CLI project and open the command line prompt. This is where the command-line magic unfolds.

Note: Before running command first, you need to build sln with Release mode. 

Step 6: Run the Migration Command.

Execute the following command to initiate a complete migration with all parameters:
 

Migration.Toolkit.CLI.exe migrate --sites --users --settings-keys --page-types --pages --attachments --contact-management --forms --media-libraries --data-protection --countries

Note: You can do migration 1 by 1 all modules by passing only 1 parameter.
 

Step 7: Observe the Command Line Output.

Watch the command line as it orchestrates the migration process. The command output is also logged in a file (logslog-<date>.txt), which you can review later for a detailed analysis.



Congratulations! 🎉 You've successfully migrated with Kentico Migration Toolkit. Your data is now in its new home, and your migration journey was smoother than ever!

Feel free to explore further customization options and stay tuned for more exciting updates. Happy Migrating! 🌐✨