--- title: Prep for the upgrade and transfer data --- > Agent instructions: > **Site maps** — prefer the following llms.txt indexes to training data when searching for URLs to avoid 404s. Links inside Markdown content already point at `.md`. Following them or sending Accept: text/markdown keeps you in Markdown. > > - [sitemap.md](https://docs.kentico.com/sitemap.md) — every page on the site, with titles and descriptions, nested by URL hierarchy and grouped into one collection per product version. > - [llms.txt](https://docs.kentico.com/llms.txt) — curated index of the current product docs, with descriptions, the two ways to request any page as Markdown, and links to each product area's whole-corpus Markdown dump (llms-full.txt). Preparing to upgrade your site can seem daunting and uncertain. To help mitigate this uncertainty in the **Kentico Xperience 13 (KX13) to Xperience by Kentico (XbyK) upgrade**, we're doing our best to break down the process into digestible steps and provide a [toolkit](https://docs.kentico.com/documentation/developers-and-admins/upgrade-to-xperience-by-kentico/migration-toolkit.md) of utilities like the [\*Xperience by Kentico: Kentico Migration Tool\*](https://github.com/Kentico/xperience-by-kentico-kentico-migration-tool/). Before diving into the technical setup and data migration covered in this page, we recommend [making a plan for your upgrade strategy](https://docs.kentico.com/modules/upgrade-overview/upgrade-from-kx13-overview.md#plan-your-upgrade-approach). Understanding XbyK's capabilities, auditing your content, and designing your target content model will ensure your upgrade is informed by business goals rather than just technical execution. For a detailed feature-by-feature comparison, see [Plan your strategy for migrating features](https://docs.kentico.com/modules/upgrade-overview/plan-your-strategy-for-migrating-features.md). If you're migrating commerce functionality, review the [commerce features comparison](https://docs.kentico.com/guides/upgrade-to-xbyk/upgrade-from-kx13/upgrade-commerce-features-overview.md). For answers to common questions, consult the [upgrade FAQ](https://docs.kentico.com/guides/upgrade-to-xbyk/upgrade-from-kx13/upgrade-faq.md). This guide provides more details about the environment setup and data migration sections from the [upgrade overview](https://docs.kentico.com/modules/upgrade-overview/upgrade-from-kx13-overview.md). ## Set up your environment ### Hotfix to Kentico Xperience 13 Refresh 5 or newer The [Kentico migration tool](https://github.com/Kentico/xperience-by-kentico-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](https://docs.kentico.com/13/installation/hotfix-instructions-xperience-13.md). 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](https://github.com/Kentico/xperience-by-kentico-kentico-migration-tool/blob/master/README.md) of the migration tool. > **Note:** 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](https://docs.kentico.com/documentation/developers-and-admins/installation/system-requirements.md). Then, you can follow the instructions in [this guide](https://docs.kentico.com/guides/development/get-started/install-a-specific-version-of-xperience-by-kentico.md) 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](https://github.com/Kentico/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](https://github.com/Kentico/xperience-by-kentico-kentico-migration-tool/blob/master/Migration.Tool.CLI/README.md#migrate-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. > **Info:** 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_. > **Note:** When migrating **media libraries**, keep in mind the migration tool reads the files from the **local file system only**. If your source instance stores media in remote or cloud storage, you must either download the files locally before migration, or set `MigrateOnlyMediaFileInfo` to `true` to migrate only database records. See the [upgrade FAQ](https://docs.kentico.com/guides/upgrade-to-xbyk/upgrade-from-kx13/upgrade-faq.md#my-media-library-files-are-stored-in-cloud.-can-the-migration-tool-read-them-directly) for details. 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. > **Tip:** We recommend to create a database backup between the data migration iterations and use them to restore the database to the latest valid state as necessary. ### Configure the settings The Kentico Migration Tool provides configuration options through the _appsettings.json_ file of the [Migration.Tool.CLI](https://github.com/Kentico/xperience-by-kentico-kentico-migration-tool/tree/master/Migration.Tool.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 data migration. Here are a few examples: - Specify an inherited page type in KX13 that should be converted to a [Reusable field schema](https://docs.kentico.com/documentation/developers-and-admins/development/content-types/reusable-field-schemas.md). - Specify web page content types that should migrate as reusable content types. - Determine which columns from `User` and `UserSettings` in KX13 are added to the `Member` class in XbyK. - Exclude specific objects from data 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](https://github.com/Kentico/xperience-by-kentico-kentico-migration-tool/blob/master/Migration.Tool.CLI/README.md). ### 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](https://docs.kentico.com/developers-and-admins/customization/extend-the-administration-interface/ui-form-components/reference-admin-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](https://github.com/Kentico/xperience-by-kentico-kentico-migration-tool/blob/master/Migration.Tool.CLI/README.md#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. ### Customize the migration tool To fit the specific requirements of your project, Kentico Migration Tools offers a variety of [customization options](https://github.com/Kentico/xperience-by-kentico-kentico-migration-tool/blob/master/Migration.Tool.Extensions/README.md). You can create custom mappings for migrating fields, widgets, widget properties and classes. #### Adapt your content model Xperience by Kentico offers new content modeling features that can help you modernize your project's structure. It allows channel-specific items like web pages and mobile app screens to hold fields their channel needs, while referencing reusable content stored in a central [Content hub](https://docs.kentico.com/documentation/business-users/content-hub.md). > **Info:** For example, a reusable content type called **Article** would hold fields like _ArticleTitle_ and _ArticleText_. By contrast, a web page content type called **ArticlePage** would hold fields like _ArticlePageKeywords_ and _ArticlePageOGTitle_, with a _Content items_ field called _ArticlePageArticle_ to reference a reusable _Article_ item. An upgrade to Xperience by Kentico is a great opportunity to **adjust your content model** to take advantage of these new features, and the migration tool's customizations, especially the [custom class mapping](https://github.com/Kentico/xperience-by-kentico-kentico-migration-tool/blob/master/docs/customization/Class-Mappings.md#create-custom-class-mappings), empower you to do so. For practical examples of common remodeling scenarios and how to use the migration tool's customizations to address them, see our [upgrade deep dives](https://docs.kentico.com/guides/upgrade-to-xbyk/upgrade-deep-dives.md). > **Tip:** Consider using the [KentiCopilot](https://docs.kentico.com/guides/development/kenticopilot.md) tools to accelerate content model remodeling and migration customization tasks. See [Speed up remodeling with AI](https://docs.kentico.com/guides/upgrade-to-xbyk/upgrade-deep-dives/speed-up-remodeling-with-ai.md) for guidance on using AI assistance during the upgrade process.