Prep for migration and transfer data

Preparing to migrate your site between platforms can seem daunting and uncertain. To help mitigate this uncertainty in the Kentico Xperience 13 (KX13) to Xperience by Kentico (XbyK) migration, we’re doing our best to break down the process into digestible steps and provide a toolkit of utilities like the Xperience by Kentico: Kentico migration tool.

This guide will provide more details about the points from the first two top-level sections of the migration overview.

Set up your environment

Hotfix to Kentico Xperience 13 Refresh 5 or newer

The Kentico migration tool relies on the presence of specific fields in system classes. For this reason, it requires Kentico Xperience 13.0.64 (Refresh 5) or newer.

If your Kentico Xperience 13 instance is currently running on a lower version, take a look at the hotfix instructions. Note that some hotfix versions contain manual steps to fix data or code affected by older bugs.

Install a compatible version of Xperience by Kentico

Because the migration tool uses the Xperience by Kentico NuGet packages to interact with its APIs, each release of the migration tool’s library corresponds to a specific Xperience by Kentico version.

You can find a compatibility version matrix in the README file of the migration tool.

When you use the dotnet command line to install Xperience by Kentico, it defaults to the newest version, which may not always correspond to a migration library version.

First, make sure your hosting environments meets the requirements for Xperience by Kentico. Then, you can follow the instructions in this guide to install a specific version of Xperience by Kentico.

Download the migration tool

You can use Git to clone the Xperience by Kentico: Kentico migration tool or simply download its code.

The environment where you install each Kentico platform must be accessible from where you install the tool.

Make sure your environment uses .NET 8.0 and meets any other requirements specified in the repository.

Before trying to build the project, make sure to restore all NuGet packages in the solution.

Migrate your data

Plan for an iterative process

The Migration CLI supports several command parameters that allow you to specify which objects from KX13 should be migrated. Options include Sites, Custom modules, Users, Members, Forms, Media libraries, Page attachments, Page types, Pages, Settings keys, Contact management-related objects, and Data protection-related objects.

Some parameters include related objects, and may depend on other parameters. For example, the media-libraries parameter requires that sites, custom modules, and users be migrated as well, and includes Media files alongside Media libraries.

When you run the migration tool multiple times, the migrated object type determines whether the tool overwrites existing objects or replaces them. This is because the tool uses bulk queries for some object types, while iterating one-by-one through others.

If you use the CLI parameters to include the following object types in multiple runs, you must delete them in between:

Contacts, from the --contact-management parameter
Activities, from the --contact-management parameter
Consent agreements, from the --data-protection parameter
Form submissions, from the --forms parameter
Custom module class data, from the --custom-modules parameter

The tool will automatically overwrite other object types, including parents and other relatives of the listed object types, so you don’t need to worry about them piling up.

Configure the settings

The Kentico migration tool provides configuration options through the appsettings.json file of the Migration.Toolkit.CLI project. Settings in this file let you provide details about how to connect your source and target environments to the migration tool and adjust various aspects of the migration. Here are a few examples:

Specify an inherited page type in KX13 that should be converted to a Reusable field schema.
Determine which columns from User and UserSettings in KX13 are added to the Member class in XbyK.
Exclude specific objects from migration.
Explicitly decide which IDs should be used as the primary key for specific objects.

The next section on this page will dive into a particularly notable configuration in this file, but you can find details about all of them in the Migration CLI README.

Set up Page Builder conversion

Page Builder components like Widgets, Page templates, and Sections can have properties that enable editors to determine their appearance and functionality. In order to specify the user interface for each property, such as a text box or dropdown list, you assign form components to the properties.

Xperience by Kentico introduces a new format for UI form components, meaning they save their data with a different structure in the database compared to their KX13 counterparts.

While XbyK supports the old format for backward compatibility, the migration tool gives you the option to convert Page Builder data with a feature called Source instance API discovery. It automatically converts serialized Page Builder data from the old format to the new format, so that you can use the new components.

The steps in the above link guide you through setting up an endpoint in your Xperience by Kentico 13 live site. This endpoint helps the migration tool convert your page builder data to the new format. Once it is in place, you only need to configure the migration tool to connect to the endpoint, and it will change the format of page builder data when you migrate pages.

What’s next?

The next guide in this series will explore later sections of the overview, covering how to convert your existing code to work in the new platform, and how to embrace new features.