Xperience by Kentico: Kentico Migration Tool

The Migration tool transfers content and other data from Kentico Xperience 13, Kentico 12 or Kentico 11 to Xperience by Kentico.

Prerequisites & Compatibility

Source

The migration currently supports the Kentico Xperience 13, Kentico 12 or Kentico 11 as the source instance. See the following sections for compatibility information and limitations of respective versions.

Kentico Xperience 13

• The source of the migration data must be a Kentico Xperience 13 instance, with Refresh 5 (hotfix 13.0.64) or newer applied.
• The development model (Core or MVC 5) does not affect the migration - both are supported.
• The source instance's database and file system must be accessible from the environment where you run the Migration toolkit.
• All features described in this repository are available for migration from Kentico Xperience 13.

Kentico 12

• The source of the migration data can be any hotfix version of the Kentico 12.
• Only MVC development model is supported by the migration tool. Any Portal Engine project that you wish to migrate to Xperience by Kentico needs to be migrated to MVC first.
• The source instance's database and file system must be accessible from the environment where you run the Migration toolkit.
• Migration of Page Builder content is not supported. Only structured data of pages is migrated.
  • As a result, source instance API discovery is also not available.
• This repository describes the migration of Kentico Xperience 13 feature set. Only features relevant to Kentico 12 are migrated for this version.

Kentico 11

• The source of the migration data can be any hotfix version of the Kentico 11. If you encounter any issues, it is recommended to update to the latest hotfix.
• Only MVC development model is supported by the migration tool. Any Portal Engine project that you wish to migrate to Xperience by Kentico needs to be migrated to MVC first.
• The source instance's database and file system must be accessible from the environment where you run the Migration toolkit.
• Only structured data of pages is migrated as Page Builder is not present in Kentico 11.
  • As a result, source instance API discovery is also not available.
• This repository describes the migration of Kentico Xperience 13 feature set. Only features relevant to Kentico 11 are migrated for this version.

Target

• The migration toolkit is periodically updated to support migration to the latest version of Xperience by Kentico. However, there may be delays between Xperience by Kentico releases and toolkit updates.
  • Currently, Xperience by Kentico 29.0.2 is tested and supported.
• The target instance's database and file system must be accessible from the environment where you run the Migration toolkit.
• The target instance's database must be empty except for data from the source instance created by previous runs of the Migration toolkit to avoid conflicts and inconsistencies.

Supported data and limitations

The Migration toolkit does not transfer all data available in the source instance. Xperience by Kentico currently provides a smaller, more focused set of features. As a result, some objects are discarded or migrated to a suitable alternative.

The Migration toolkit only supports content and objects stored in the database and related binary data on the file system, such as media library files. Code, customizations, and any other types of content need to be migrated manually to the target project and adjusted for Xperience by Kentico.

Currently, the Migration toolkit supports the following types of data:

• Sites

  • The toolkit migrates each site on the source to a website channel object in Xperience by Kentico.

• Cultures

  • The set of cultures used across all sites in the source gets mapped to a language in the Languages application.

• Content types (Page types in earlier Kentico versions)

  • The Migration toolkit attempts to map the Data type and Form control of page type fields to an appropriate equivalent in Xperience by Kentico. This mapping is not always possible and does not work for custom data types or form controls. We recommend checking your content type fields after the migration and adjusting them if necessary.
  • The migration includes only page types assigned to at least one site on the source instance.
  • Xperience by Kentico currently does not support:
    • Macro expressions in page type field default values or other settings. Content type fields containing macros will not work correctly after the migration.
    • Categories for page type fields. Field categories are not migrated with page types.
    • Page type inheritance. Page types that inherit fields are migrated including all inherited fields but the binding to the parent page type is not preserved.
      • However, you can create reusable field schemas for page types from which other page types inherit.
  • All migrated Content types have the Include in routing option enabled (the migration never creates pages without URL and routing).

• Pages

  • The migration includes the following versions of pages:
    • Published
    • Latest draft version - for published pages, the version is migrated to the Draft workflow step; for pages that do not have a published version, the version is migrated to the Draft (initial) workflow step.
    • Archived
  • Each page gets assigned under its corresponding website channel.
  • Linked pages are currently not supported in Xperience by Kentico. The migration creates standard page copies for any linked pages on the source instance.
  • Page permissions (ACLs) are currently not supported in Xperience by Kentico and are not migrated.
  • Migration of Page Builder content is only available for Kentico Xperience 13.

• Page attachments

  • Page attachments are not supported in Xperience by Kentico. Attachments are migrated into media libraries. See Migration.Toolkit.CLI/README.md - Attachments for detailed information about the conversion process.

• Preset page templates (Custom page templates in Kentico Xperience 13)

  • Migration of custom page templates is only available for Kentico Xperience 13.

• Media libraries and media files

  • Media library permissions are currently not supported in Xperience by Kentico and are not migrated.

• Forms

  • The migration does not include the content of form autoresponder and notification emails. You can migrate form autoresponders to Xperience by Kentico manually by copying your HTML code and content into Email templates and Emails. See Emails.

• Users

  • Xperience by Kentico uses separate entities for users with access to the administration interface (CMS_User table) and live site visitor accounts (CMS_Member table). Consequently, only users whose Privilege level is Editor or higher are migrated (Users -> edit a user -> General tab).
  • Users in Xperience by Kentico must have an email address. Migration is only supported for users who have a unique email address value on the source instance.
  • Custom user fields are an optional part of module class migration.
  • Live site users are represented using a separate Member entity and stored in the CMS_Member table. The migration identifies live site users as those without access to the administration interface - accounts with Privilege level set to None (Users -> edit a user -> General tab).

• Roles

  • Only roles that have at least one user whose Privilege level is set to Editor and above are migrated.
  • Because Xperience by Kentico uses a different permission model, no existing role permissions or UI personalization settings are migrated. After the migration, the permissions for each role must be configured again.

• Contacts

  • The target instance's OMContact and OMActivity database tables must be empty for performance reasons.
  • Custom contact fields are an optional part of module class migration.

• Activities

• Consents and consent agreements

• Modules and classes

  • The migration includes the following:
    • Custom modules
    • All classes associated with custom modules
    • All data stored within custom module classes
    • The following customizable system classes and their custom fields: User, Media file, Contact management - Account (however, accounts are currently not supported in Xperience by Kentico), Contact management - Contact
  • Module and class migration does NOT include:
    • UI elements and all related user interface settings. The administration of Xperience by Kentico uses a different technology stack than earlier Kentico versions and is incompatible. To learn how to build the administration UI, see Extend the administration interface and Example - Offices management application.
    • Alternative forms under classes and UI-related configuration of class fields (field labels, Form controls, etc.). After the migration, you must manually create the appropriate UI forms in Xperience by Kentico.
    • Custom settings under modules, which are currently not supported in Xperience by Kentico
    • Module permissions (permissions work differently in Xperience by Kentico - see Role management and UI page permission checks)
    • As with all object types, the migration toolkit does not transfer code files to the target project. You must manually move all code files generated for your custom classes (Info, InfoProvider, etc.).

• Custom tables

  • Custom tables are not supported in Xperience by Kentico. Data from custom tables is migrated to the target instance as custom modules.
  • The migration only transfers data from custom tables to the custom module (CMS_Resource) database table.
  • Any user interface, listings, filters, and other functionality related to migrated custom tables needs to be implemented in the target instance.

• Setting values

  • The migration only transfers the settings that exist in Xperience by Kentico.
  • The migration excludes site-specific settings that do not have a corresponding website channel-specific alternative in Xperience by Kentico.

• Countries and states

Unsupported data

The following types of data exist in Xperience by Kentico but are currently not supported by the Migration toolkit:

• Contact groups
  • Static contact groups are currently not supported in Xperience by Kentico.
  • The condition format for dynamic contact groups is not compatible. To migrate contact groups:
    1. Migrate your contacts using the toolkit.
    2. Create the contact groups manually in Xperience by Kentico.
    3. Build equivalent conditions.
    4. Recalculate the contact groups.
• License keys
  • Xperience by Kentico uses a different license key format.

Additionally, object values or other content with Macros will not work correctly after the migration. Macro expressions are currently not supported for most data in Xperience by Kentico.

Get started

Follow the steps below to run the Migration toolkit:

1. Clone or download the Migration.Toolkit source code from this repository.

2. Open the Migration.Toolkit.sln solution in Visual Studio.

3. Configure the options in the Migration.Toolkit.CLI/appsettings.json configuration file. See Migration.Toolkit.CLI/README.md - Configuration for details.

4. Rebuild the solution and restore all required NuGet packages.

5. Open the command line prompt.

6. Navigate to the output directory of the Migration.Toolkit.CLI project.

7. Run the Migration.Toolkit.CLI.exe migrate command.

   • The following example shows the command with all parameters for complete migration:

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

8. Observe the command line output. The command output is also stored in a log file (logs\log-<date>.txt under the output directory by default), which you can review later.

9. Review the migration protocol, which provides information about the result of the migration, lists required manual steps, etc.

   • You can find the protocol in the location specified by the MigrationProtocolPath key in the appsettings.json configuration file.
   • For more information, see Migration.Toolkit.CLI/MIGRATION_PROTOCOL_REFERENCE.md.

The data is now migrated to the target Xperience by Kentico instance according to your configuration. See Migration.Toolkit.CLI/README.md for detailed information about the migration CLI, configuration options, instructions related to individual object types, and manual migration steps.

Contributing

See CONTRIBUTING.md to learn how to file issues, start discussions, and submit contributions.

Please provide all available information about the problem or error when submitting issues. If possible, include the command line output log file and migration protocol generated by the Migration.Toolkit.CLI.exe migrate command.

License

Distributed under the MIT License. See LICENSE.md for more information.

Questions & Support

See the Kentico home repository for more information about the products and general advice on submitting questions.