Migration overview
If you’re in charge of moving project from Kentico Xperience 13 (KX13) to Xperience by Kentico (XbyK), or considering doing so, you may have some questions about what that process looks like at a high level.
You’ve probably come across the Kentico Migration Tool for Xperience by Kentico, but as you might imagine, simply running the tool is probably not the only magical step to completely migrate your whole solution.
Let’s take a look at the process together. There are four main parts to consider:
- Set up your environment and configure the migration tool
- Migrate your data and binary files using the migration tool
- Migrate your code and any custom artifacts not covered by the migration tool
- Think about the future and explore the full potential of Xperience by Kentico
In case you’re looking for more explanation than some orange pill shapes on a diagram, let’s break down each point.
Set up your environment
The first step of the migration is to make sure your environment supports the migration tool and both platforms, and to prepare them for migration.
Hotfix to Kentico Xperience 13 Refresh 5 or newer
Make sure to your Kentico Xperience 13 instance is running on Refresh 5 (hotfix 13.0.64) or newer. If not, make sure to apply a hotfix within the supported range.
Install a compatible version of Xperience by Kentico
Check the table in the README file of the Xperience by Kentico: Kentico migration tool to see which versions of Xperience by Kentico and the migration library are compatible.
Download the migration tool
Clone or download the Xperience by Kentico: Kentico migration tool. Make sure your environment meets the requirements to run the solution specified in the repository.
Migrate your data
Once the environment is ready, you can migrate data from Kentico Xperience 13 to Xperience by Kentico.
Thanks to the CLI parameters that allow you to specify which objects to migrate, you can iteratively migrate data in multiple runs before migrating code. Alternatively, you can do so in parallel with code updates.
Configure the settings
Follow the guidance in the Usage guide and the CLI README to configure the details of your migration.
Set up Page Builder conversion
If you use Page Builder in your Kentico Xperience 13 instance, consider paying special attention to the section about Source instance API discovery. By adding a special endpoint to your current live site, you can enable the tool to convert your Page Builder data to a format that uses Xperience by Kentico’s new UI form components.
Migrate your code
While past Kentico releases were built as expansions on previous versions, Xperience by Kentico is a brand new product, built from the ground up. It shares many similarities with legacy Kentico products, but also has some important differences you will have to account for when transferring your code.
Update content querying
Xperience replaces the DocumentQuery and MultiDocumentQuery APIs from legacy Kentico versions with the Content item API. Your team will need to update code that retrieved page data to work with the new API.
Adjust Page Builder components
If you choose to enable Source instance API discovery, you will need to change the editing components used by the properties of your Page Builder components to the new admin UI components.
Re-home custom tables
Xperience by Kentico does not have a direct analog for the Custom tables functionality in legacy Kentico products.
The Kentico migration tool transfers each custom table to a custom object type, but does not provide a user interface. Your team must create a UI for each class, or alternatively, convert the data to reusable content items that editors can manage through the Content hub.
Convert custom module pages
Xperience’s admin UI is no longer built with web forms, so your team will have to recreate any custom module pages as UI pages in the new admin.
Alter auth and user management
Where legacy Kentico products utilized the User entity to represent users of the administration interface and the live site, Xperience by Kentico has a separate Member object type representing those who sign in to the live site. Your team must change old registration and authentication code to work with members.
Choose a search integration
Xperience by Kentico does not include search functionality out-of-box, but rather provides three integration options: Lucene, Azure AI search, and Algolia. You need to recreate search functionality through one of these services.
Address differences in localization
Xperience by Kentico supports localization, with the migration tool automatically transferring multilingual pages and Cultures (as Languages). However, some features are not covered.
Kentico Xperience 13 allowed you to add custom resource strings to the database through the administration interface. Xperience by Kentico does not include this feature out-of-box, so your team must use a resource file, or store custom strings as content items of a specific type in the Content hub.
Alternatively, you can use or modify Nittin’s Xperience community localization module for this functionality, or implement your own custom module.
Migrate commerce
Xperience by Kentico does not yet include an out-of-box commerce suite like Kentico Xperience 13. We’ve got you covered, though:
You can continue to host your products and calculation in KX13 while displaying them on your Xperience by Kentico site using our E-commerce bridge integration. Alternately, you can utilize the Shopify integration.
Handle marketing changes
Xperience by Kentico has many marketing features, but it does not aim for feature parity with Kentico Xperience 13, so there are some differences you’ll need to consider when transferring your project. Xperience by Kentico does not support personas or A/B tests natively, and it does not cover all possible marketing automation scenarios.
However, we do offer pathways to help your team handle these potential challenges. Learn more in our Plan your strategy for migrating features guide.
Think about the future
Depending on your constraints, you may want to consider ways of improving your project with Xperience’s new offerings.
Adapt your content model
Xperience by Kentico boasts a modern, flexible content model where reusable items are referenced from multiple different channels, such as web sites, microsites, mobile applications, and email campaigns.
In order to take advantage of this headless-enabling flexibility, we recommend that you consider adapting your content to work in this way, leaving web-specific metadata in a website channel while making the meat of your structured content reusable.
Utilize new capabilities
As discussed earlier, we developed Xperience by Kentico from the ground up as a new product. This means that it contains features that work differently than analogous functionality in Kentico Xperience 13, or that didn’t exist in that version altogether. Here are some examples of new features you can take advantage of in Xperience by Kentico:
- Taxonomies and their tags represent hierarchical structures of categorization, and cover more advanced content scenarios than tags and categories in Kentico Xperience 13.
- Smart folders allow your editors to dynamically filter and group content items, and can feed API queries on the live site.
- Reusable field schemas allow for groups of fields to shared across many content types, with changes reflecting across all content types that use them immediately.
What’s next?
The next guides in this series will dive into a bit more detail about each of the points highlighted in this overview. They will cover high-level looks at analogous features between platforms, preparation and data migration, and code conversion and new features.
You can also find more information in the documentation and the Xperience by Kentico: Kentico Migration Tool repository.