This repository is part of the Xperience by Kentico Migration Toolkit.
The Kentico Migration Tool transfers content and other data from Kentico Xperience 13, Kentico 12 or Kentico 11 to Xperience by Kentico.
The tool migrates data models and content only. Code migration is not supported. Migrations can be performed multiple times with built-in and custom data transformations.
This repository contains the data migration tool and its technical reference documentation. For comprehensive guidance on upgrading from Kentico Xperience 13 to Xperience by Kentico, including planning, walkthroughs, and advanced techniques, see the Learn portal upgrade guides.
Quick Links:
- Upgrade overview - High-level overview of the upgrade process
- Upgrades FAQ for architects and team leads - Common questions and challenges
- Plan your strategy - Feature comparison and effort estimation
- Upgrade walkthrough - Hands-on tutorial with the Dancing Goat sample site
- Advanced upgrade deep dives - Developer-focused guides for customizing migrations and handling complex scenarios
Important
When planning an upgrade, note special considerations for deploying to production and deploying to SaaS.
Technical reference documentation for configuring and running the migration tool:
| Document | Purpose |
|---|---|
| Migration CLI README | Commands, configuration options, object-specific instructions |
| Supported Data | Complete list of what can/cannot be migrated |
| Extensions README | How to create custom migrations |
| Repository Structure | Project organization, component relationships, codebase navigation |
| Contributing Setup | For contributors to this tool |
The migration tool transfers data from source databases (K11/KX12/KX13) to Xperience by Kentico, transforming data structures as needed:
The migration follows six sequential steps:
- Execute CLI 'migrate' Command - Initiates the process
- Read configuration - Loads settings from appsettings.json
- Load source data - Retrieves data from source database (K11/KX12/KX13), filesystem (media/attachments), and API (widget info for KX13)
- Transform Data - Applies built-in mappers and custom migrations (field, widget, and class mappings)
- Write to target - Uses Universal Migration Tool (primary), XbyK API, or Bulk SQL copy to recreate content and other data in your target Xperience by Kentico instance.
- Generate Reports - Outputs console logs and log files
The migration tool is:
- Iterative - Supports multiple runs that update existing data without creating duplicates (UPSERT behavior)
- Selective - Migrates only specific data types using command parameters
- Extensible - Applies custom transformations for project-specific requirements
Before running the migration, ensure you have:
-
Source instance (K11/KX12/KX13) running and accessible
- KX13 must be Refresh 5 (hotfix 13.0.64) or higher
-
Target Xperience by Kentico instance set up and running
- must be compatible with the version of migration tool (see version compatibility matrix)
-
.NET 8.0 or newer SDK installed
-
Kentico Migration Tool source code cloned or downloaded from this repository
[!NOTE] We recommend to maintain a separate copy of the Migration Tool per project to keep project-specific configurations and customizations isolated.
Need help with instance setup? The Migration CLI README provides detailed instructions for configuring both source and target instances.
For a lift-and-shift migration, use the migration tool's default configuration:
-
Set up your instances - Ensure both source and target instances are accessible. The source instance must be running. The target instance must not be running.
-
Configure connections - Update
appsettings.jsonin theMigration.Tool.CLIproject with database connection strings. -
Build the solution - Open
Migration.Tool.slnin your IDE and build in Release mode for optimal performance. (Use Debug mode when developing custom migrations or troubleshooting issues.) -
Run the migration - Navigate to the output directory and execute the CLI tool:
cd .\Migration.Tool.CLI\bin\Release\net8.0 .\Migration.Tool.CLI.exe migrate --sites --users --page-types --pages
For a complete migration with all data types:
.\Migration.Tool.CLI.exe migrate --sites --custom-modules --users --settings-keys --page-types --pages --type-restrictions --contact-management --forms --media-libraries --data-protection --custom-tables --members --categories
-
Review results - Check console output and log files for issues or manual steps:
- Console shows real-time progress and results
- Log files capture detailed execution logs (
logs\log-<date>.txt)
Note
What gets migrated? See Supported Data for a complete list of data types and any limitations.
Tip
First-time user? See the Migration CLI Setup Guide for detailed instructions on configuring source and target instances, understanding appsettings.json options, and command parameters.
Learning by doing? Follow our Upgrade Walkthrough - a step-by-step, code-along guide using the Dancing Goat sample site. The guide covers both data migration and code adjustments to display a Kentico Xperience 13 page seamlessly in Xperience by Kentico.
The migration tool handles standard data transformations automatically. However, you may need to customize the migration process for:
- Project-specific custom implementations - When migrating custom field types, Page Builder widgets with non-standard properties, or custom modules/tables requiring specialized data handling
- Content model optimization - When restructuring your content to better align with Xperience by Kentico architecture, such as converting web pages to reusable content items, flattening hierarchical structures, or transforming Page Builder widget data
To understand when and how to implement customizations:
- Review the Repository Structure to understand how the migration tool components interact.
- Consult the Extensions Guide for detailed instructions on customizing migration.
View all project releases.
| Xperience Version | Library Version |
|---|---|
| >= 31.0.0 | >= 4.0.0 |
| >= 30.12.0 | >= 3.20.0 |
| >= 30.11.0 | >= 3.18.0 |
| >= 30.10.1 | >= 3.16.0 |
| >= 30.8.0 | >= 3.12.0 |
| >= 30.6.0 | >= 3.8.0 |
| >= 30.5.1 | >= 3.6.0 |
| >= 30.4.0 | >= 3.4.0 |
| >= 30.3.1 | >= 3.3.0 |
| >= 30.2.0 | >= 3.0.0 |
| >= 30.1.1 | >= 2.3.0 |
| >= 30.0.0 | >= 2.0.0 |
| >= 29.7.0 | >= 1.6.0 |
| >= 29.6.0 | >= 1.4.0 |
| >= 29.5.2 | >= 1.3.0 |
| >= 29.3.3 | >= 1.2.0 |
| >= 29.2.0 | >= 1.1.0 |
| >= 29.1.0 | >= 1.0.0 |
When creating an issue, provide all available information about the problem or error. Include the command line output log file generated by the Migration.Tool.CLI.exe migrate command when possible.
For guidelines on contributing to Kentico open source software, see Kentico's CONTRIBUTING.md and follow Kentico's CODE_OF_CONDUCT.
Instructions and technical details for contributing to this project can be found in Contributing Setup.
Distributed under the MIT License. See LICENSE.md for more information.
This project has Full support by 7-day bug-fix policy:
- Bug fixes are applied to the latest version only (no backporting to previous releases)
- The Migration Tool is a temporary utility designed for one-time migrations, not long-term production software
To report bugs, upgrade to the latest Migration Tool version before submitting issues.
See SUPPORT.md for more information.
Important
Before submitting a support ticket, please read about the best practices on reporting Kentico Migration Tool and upgrade issues.
For any security issues, see Kentico's SECURITY.md.