Migration CLI

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

The migration is performed by running a command for the .NET CLI.

Set up the source instance

The source instance must not use a separated contact management database, it is recommended that you rejoin the contact management database before proceeding with the migration.

Set up the target instance

The target of the migration must be an Xperience by Kentico instance that fulfills the following requirements:

The instance's database and file system must be accessible from the environment where you run the migration.
The target application must not be running when you start the migration.
The target instance must be empty except for data from the source instance created by previous runs of this tool.
For performance optimization, the migration transfers certain objects using bulk SQL queries. As a result, you always need to delete all objects of the following types before running repeated migrations:
- Contacts, including their Activities (when using the migrate --contact-management parameter)
- Consent agreements (when using the migrate --data-protection parameter)
- Form submissions (when using the migrate --forms parameter)
- Custom module class data (when using the --custom-modules parameter)

To create a suitable target instance, install a new Xperience by Kentico project using the Boilerplate project template.

Migrate data

To perform the migration:

Make sure the target instance is set up correctly.
Configure the options in the Migration.Tool.CLI project's appsettings.json file.
Compile the Migration.Tool.CLI project.
Open the command line prompt.
Navigate to the project's output directory.
Run the Migration.Tool.CLI.exe migrate command with parameters according to your requirements.
Observe the command line output and review the migration protocol, which provides information about the result of the migration, lists required manual steps, etc.
On SaaS projects, you need to manually move content item asset files. See Content items for more information.

Migrate command parameters

Command usage:

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

Parameter	Description	Dependencies
`--sites`	Enables migration of sites to website channels. The site's basic properties and settings are transferred to the target instance.
`--custom-modules`	Enables migration of custom modules, custom module classes and their data, and custom fields in supported system classes. See: Migration details for specific object types - Custom modules and classes	`--sites`
`--custom-tables`	Enables migration of custom tables. See: Migration details for specific object types - Custom tables
`--users`	Enables migration of users and roles. See: Migration details for specific object types - Users	`--sites`, `--custom-modules`
`--members`	Enables migration of live site user accounts to members. See: Migration details for specific object types - Members	`--sites`, `--custom-modules`
`--settings-keys`	Enables migration of values for settings that are available in Xperience by Kentico.	`--sites`
`--page-types`	Enables migration of content types (originally page types in Kentico Xperience 13) and preset page templates (originally custom page templates). Required to migrate Pages. See: Migration details for specific object types - Content types	`--sites`
`--pages`	Enables migration of pages. The target instance must not contain pages other than those created by previous runs of the Kentico Migration Tool. See: Migration details for specific object types - Pages	`--sites`, `--users`, `--page-types`
`--categories`	Enables migration of categories to taxonomies. Xperience by Kentico uses a different approach to categorization. Categories are migrated to taxonomies and selected categories for each page are assigned to pages in the target instance via a reusable field schema. See `Categories`.	`--sites`, `--users`, `--pagetypes`, `--pages`
`--attachments`	Enables migration of page attachments to content hub as content item assets (page attachments are not supported in Xperience by Kentico). See: Migration details for specific object types - Attachments	`--sites`, `--custom-modules`
`--contact-management`	Enables migration of contacts and activities. The target instance must not contain any contacts or activities. May run for a long time depending on the number of contacts in the source database.	`--users`, `--custom-modules`
`--data-protection`	Enables migration of consents and consent agreements.	`--sites`, `--users`, `--contact management`
`--forms`	Enables migration of forms and submitted form data. See: Migration details for specific object types - Forms	`--sites`, `--custom-modules`, `--users`
`--media-libraries`	Enables migration of media libraries to content hub as content item assets. This behavior can be adjusted by `MigrateOnlyMediaFileInfo` and `MigrateMediaToMediaLibrary` configuration options.	`--sites`, `--custom-modules`, `--users`
`--countries`	Enables migration of countries and states. Xperience by Kentico currently uses countries and states to fill selectors when editing contacts and contact group conditions.
`--bypass-dependency-check`	Skips the migrate command's dependency check. Use for repeated runs of the migration if you know that dependencies were already migrated successfully (for example `--page types` when migrating pages).

Examples

Migration.Tool.CLI.exe migrate --sites --custom-modules --users --settings-keys --media-libraries --page-types --pages
- First migration that includes the site object, custom modules and classes, users, setting key values, media libraries, page types and pages
Migration.Tool.CLI.exe migrate --page-types --pages --bypass-dependency-check
- Repeated migration only for page types and pages, if you know that sites and users were already migrated successfully.
Migration.Tool.CLI.exe migrate --pages --bypass-dependency-check
- Repeated migration only for pages, if you know that page types, sites, and users were already migrated successfully.

Migration details for specific object types

Content types

Content types are named Page types in earlier Kentico products.

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.
Page type inheritance. You cannot migrate page types that inherit fields from other types.
Categories for page type fields. Field categories are not migrated with page types.

The Kentico Migration Tool attempts to map the Data type and Form control of page type fields to an appropriate equivalent in Xperience by Kentico. This is not always possible, and cannot be done for custom data types or form controls. We recommend that you check your content type fields after the migration and adjust them if necessary.

The following table describes how the Kentico Migration Tool maps the data types and form controls/components of page type fields:

KX13/12/11 Data type	XbyK Data type	KX13/12/11 Form control	XbyK Form component
Text	Text	Text box	Text input
Text	Text	Drop-down list	Dropdown selector
Text	Text	Radio buttons	Radio button group
Text	Text	Text area	Text area
Text	Text	other	Text input
Long text	Long text	Rich text editor	Rich text editor
Long text	Long text	Text box	Text input
Long text	Long text	Drop-down list	Dropdown selector
Long text	Long text	Text area	Text area
Long text	Long text	other	Rich text editor
Integer number	Integer number	any	Number input
Long integer number	Long integer number	any	Number input
Floating-point number	Floating-point number	any	Number input
Decimal number	Decimal number	any	Decimal number input
Date and time	Date and time	any	Datetime input
Date	Date	any	Date input
Time interval	Time interval	any	None (not supported)
Boolean (Yes/No)	Boolean (Yes/No)	any	Check box
Attachments	Media files	any (Attachments)	Media file selector (the attachments are converted to media files)
File	Media files	any (Direct uploader)	Media file selector (the attachments are converted to media files)
Unique identifier (Guid)	Unique identifier (Guid)	any	None (not supported)
Pages	Pages	any (Pages)	Page selector

Additionally, you can enable the Conversion of text fields with media links (Media selection form control) to content item assets or media library files by setting the OptInFeatures.CustomMigration.FieldMigrations configuration option.

Some Form components used by content type fields in Xperience by Kentico store data differently than their equivalent Form control in Xperience 13. To ensure that content is displayed correctly on pages, you must manually adjust your website's implementation to match the new data format. See Editing components in Xperience by Kentico to learn more about some of the most common components and selectors.

Reusable field schemas

You can create reusable field schemas from page types from which other page types inherit, by setting the Settings.CreateReusableFieldSchemaForClasses configuration option.

Content items

If the target instance is a SaaS project (installed with the --cloud option) you need to manually move any content item asset binary files from the default location (~/assets) to the location specified in the StorageInitializationModule.cs file, which is ~/$StorageAssets/default/assets by default. This is necessary to enable the system to map the asset binary files to the Azure Blob storage.

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
URLs are migrated depending on the source instance version:
- For Kentico Xperience 13, the migration:
  - includes the URL paths of pages and Former URLs
  - does not include Alternative URLs
- For Kentico 12 and Kentico 11, URL paths are not migrated. Instead, a default URL path is created from the DocumentUrlPath or NodeAliasPath.
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 migrated into Xperience by Kentico.
Migration of page builder content is only available for Kentico Xperience 13.

Page builder content

⚠️ Page builder content migration is only available when migrating from Kentico Xperience 13.

By default, JSON data storing the page builder content of pages and custom page templates is migrated directly without modifications. On the target Xperience by Kentico instance, the migrated data can work in the Page Builder's legacy compatibility mode. However, we strongly recommend updating your codebase to the new Xperience by Kentico components.

The Kentico Migration Tool provides an advanced migration mode for page builder content that utilizes API discovery on the source instance. To learn more details and how to configure this feature, see Source instance API discovery.

Custom modules and classes

The migration includes the following:

Custom modules
- Note: The CMS. prefix/namespace is reserved for system modules and not allowed in custom module code names. If present, this code name prefix is removed during the migration.
All classes belonging under custom modules
All data stored within custom module classes
The following customizable system classes and their custom fields:
- Membership > User
- Media libraries > Media file
- Contact management > Contact management - Account (however, accounts are currently not supported in Xperience by Kentico)
- Contact management > 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 Kentico Xperience 13 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.). You need to manually create appropriate UI forms in Xperience by Kentico after the migration.
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 Kentico Migration Tool does not transfer code files to the target project. You need to manually move all code files generated for your custom classes (Info, InfoProvider, etc.).

To learn more about custom modules and classes in Xperience by Kentico, see the Object types documentation.

Custom tables

The migration includes the following:

Basic information about custom tables (from the CMS_Class table) is migrated to the custom module table (CMS_Resource) as a special customtables resource.
Content of individual custom tables is migrated as module classes.

Custom table migration does NOT include:

Any other data related to custom tables (queries, alternative forms) are discarded by the migration.
UI elements related to custom tables such as listings and filters are not migrated and need to be implemented. The administration of Xperience by Kentico uses a different technology stack than Kentico Xperience 13 and is incompatible. To learn how to build the administration UI, see Extend the administration interface and Example - Offices management application.

Media libraries

Media library files are migrated as content item assets to the content hub into a content folder <site_name>/<library_folder>. All assets are created in the default language of the respective site. Migrated assets are created as content items of a Legacy media file content type (code name Legacy.Mediafile) created by the tool.

If required, you can configure the tool to instead migrate media libraries as media libraries on the target instance.

Attachments

Attachment files are migrated as content item assets to the content hub into a content folder <site_name>/__Attachments. Assets are created in the specified language if the language is available (e.g., attachments of pages). Migrated assets are created as content items of a Legacy attachment content type (code name Legacy.Attachment) created by the tool.

If required, you can configure the tool to instead migrate attachments as media libraries on the target instance.

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

Note: 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 set to Editor and above are migrated (Users -> edit a user -> General tab) via the --users command. To migrate live site accounts as well, use --members.

The command migrates all users with access to the administration interface. Note the following expected behavior:

The 'administrator' user account is only transferred from the source if it does not exist on the target instance.
The 'public' system user is updated, and all bindings (e.g., the site binding) are mapped automatically on the target instance.
Site bindings are updated automatically for all migrated users.
Users in Xperience by Kentico must have an email address. Migration is only supported for users with a unique email address on the source instance.
- If you encounter issues related to email validation, you can change the default validation behavior via the CMSEmailValidationRegex application key.
Custom user fields can be migrated together with module classes.

Additionally, the command migrates all roles and user-role bindings for users whose Privilege level is Editor or higher.

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.

Members

In Xperience by Kentico, 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. That is, only those accounts whose Privilege level is set to None (Users -> edit a user -> General tab) are migrated.

The migration includes:

All system fields from the CMS_User and CMS_UserSettings tables. You can customize which fields are migrated via the MemberIncludeUserSystemFields configuration option. See configuration.
All custom fields added to the CMS_User and CMS_UserSettings tables are migrated under CMS_Member. The columns specified in the MemberIncludeSystemFields option are appended to the CMS_Member table in the order in which they were specified. As an example, take the following CMS_Member columns
```
|MemberId|MemberEmail|...|MemberSecurityStamp|
```
And the following Migration.Tool.CLI/appsettings.json configuration.
```
{
  "MemberIncludeUserSystemFields": "FirstName|LastName|UserPrivilegeLevel"
}
```
This will result in the following CMS_Member structure after migration.
```
|MemberId|MemberEmail|...|MemberSecurityStamp|FirstName|LastName|UserPrivilegeLevel|`
```
If you are migrating custom fields, the --custom-modules migration command must be run before the --members command. For example:
```
Migration.Tool.CLI.exe migrate --sites --custom-modules  --users --members
```

The migration DOES NOT include:

External sign-in information associated with each account (e.g., Google or Facebook logins).

User password hashes from the CMS_User.UserPassword column.

After the migration, the corresponding CMS_Member.MemberPassword in the target Xperience by Kentico instance is NULL. This means that the migrated accounts CANNOT be used to sign in to the system under any circumstances. The account owners must first reset their password via ASP.NET Identity.

See Forms authentication for a sample password reset process that can be adapted for this scenario. The general flow consists of these steps:

Select the migrated member accounts.

// Selects members whose password is null and who don't use external providers to sign in
var migratedMembers =
        MemberInfo.Provider
                .Get()
                .WhereNull("MemberPassword")
                .WhereEquals("MemberIsExternal", 0);

Generate password reset tokens for each account using UserManager.GeneratePasswordResetTokenAsync(member).

Send the password reset email to each account using IEmailService.

await emailService
        .SendEmail(new EmailMessage()
        {
            Recipients = member.Email,
            Subject = "Password reset request",
            // {resetURL} targets a controller action with the password reset form
            Body = $"To reset your account's password, click <a href=\"{resetUrl}\">here</a>."
        });

Contacts

Custom contact fields can be migrated together with module classes.
For performance reasons, contacts and related objects are migrated using bulk SQL queries. As a result, you always need to delete all Contacts, Activities and Consent agreements before running the migration (when using the migrate --contact-management parameter).

Configuration

Before you run the migration, configure options in the Migration.Tool.CLI/appsettings.json file.

Add the options under the Settings section in the configuration file.

Configuration	Description
KxConnectionString	The connection string to the source Kentico Xperience 13, Kentico 12, or Kentico 11 database.
KxCmsDirPath	The absolute file system path of the CMS folder in the source Kentico Xperience 13, Kentico 12, or Kentico 11 administration project. Required to migrate media library files.
XbyKDirPath	The absolute file system path of the root of the target Xperience by Kentico project. Required to migrate media library and page attachment files.
XbyKApiSettings	Configuration options set for the API when creating migrated objects in the target application. The `ConnectionStrings.CMSConnectionString`option is required - set the connection string to the target Xperience by Kentico database (the same value as obsolete `XbKConnectionString`).
MigrationProtocolPath	The absolute file system path of the location where the migration protocol file is generated. For example: `"C:\\Logs\\Migration.Tool.Protocol.log"`
MigrateOnlyMediaFileInfo	If set to `true`, only the database representations of media files are migrated, without the files in the media folder in the project's file system. For example, enable this option if your media library files are mapped to a shared directory or Cloud storage. If `false`, media files are migrated based on the `KxCmsDirPath` location.
MigrateMediaToMediaLibrary	Determines whether media library files and attachments from the source instance are migrated to the target instance as media libraries or as content item assets in the content hub. The default value is `false` – media files and attachments are migrated as content item assets. See Convert attachments and media library files to media libraries instad of content item assets
MemberIncludeUserSystemFields	Determines which system fields from the CMS_User and CMS_UserSettings tables are migrated to CMS_Member in Xperience by Kentico. Fields that do not exist in CMS_Member are automatically created. The sample `appsettings.json` file included with the tool by default includes all user fields that can be migrated from Kentico Xperience 13. Exclude specific fields from the migration by removing them from this configuration option.
UseOmActivityNodeRelationAutofix	Determines how the migration handles references from Contact management activities to non-existing pages. Possible options: `DiscardData` - faulty references are removed, `AttemptFix` - references are updated to the IDs of corresponding pages created by the migration, `Error` - an error is reported and the reference can be translated or otherwise handled manually
UseOmActivitySiteRelationAutofix	Determines how the migration handles site references from Contact management activities. Possible options: `DiscardData`,`AttemptFix`,`Error`
EntityConfigurations	Contains options that allow you to fine-tune the migration of specific object types.
EntityConfigurations.<object table name>.ExcludeCodeNames	Excludes objects with the specified code names from the migration.
CreateReusableFieldSchemaForClasses	Specifies which page types are also converted to reusable field schemas.
OptInFeatures.QuerySourceInstanceApi.Enabled	If `true`, source instance API discovery is enabled to allow advanced migration of page builder content for pages and page templates.
OptInFeatures.QuerySourceInstanceApi.Connections	To use source instance API discovery, you need to add a connection JSON object containing the following values: `SourceInstanceUri` - the base URI where the source instance's live site application is running. `Secret` - the secret that you set in the ToolkitApiController.cs file on the source instance.
OptInFeatures.CustomMigration.FieldMigrations	Enables conversion of media selection text fields to content item assets or media library files. See Convert text fields with media links for more information.

Example

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "System": "Warning",
      "Microsoft": "Warning"
    },
    "MinimumLevel": {
      "Default": "Information",
      "System": "Warning",
      "Microsoft": "Warning"
    },
    "pathFormat": "logs/log.txt"
  },
  "Settings": {
    "KxConnectionString": "Data Source=myserver;Initial Catalog=Xperience13;Integrated Security=True;Persist Security Info=False;Connect Timeout=120;Encrypt=False;Current Language=English;",
    "KxCmsDirPath": "C:\\inetpub\\wwwroot\\Xperience13\\CMS",
    "XbyKDirPath": "C:\\inetpub\\wwwroot\\XP_Target",
    "XbyKApiSettings": {
      "ConnectionStrings": {
        "CMSConnectionString": "Data Source=myserver;Initial Catalog=XperienceByKentico;Integrated Security=True;Persist Security Info=False;Connect Timeout=120;Encrypt=False;Current Language=English;"
      }
    },
    "MigrationProtocolPath": "C:\\_Development\\xperience-migration-toolkit-master\\Migration.Toolkit.Protocol.log",
    "MemberIncludeUserSystemFields": "FirstName|MiddleName|LastName|FullName|UserPrivilegeLevel|UserIsExternal|LastLogon|UserLastModified|UserGender|UserDateOfBirth",
    "MigrateOnlyMediaFileInfo": false,
    "MigrateMediaToMediaLibrary": false,
    "UseOmActivityNodeRelationAutofix": "AttemptFix",
    "UseOmActivitySiteRelationAutofix": "AttemptFix",
    "EntityConfigurations": {
      "CMS_Site": {
        "ExplicitPrimaryKeyMapping": {
          "SiteID": {
            "1": 1
          }
        }
      },
      "CMS_Class": {
        "ExcludeCodeNames": [
          "CMS.File",
          "CMS.MenuItem",
          "ACME.News",
          "ACME.Office",
          "CMS.Blog",
          "CMS.BlogPost"
        ]
      },
      "CMS_SettingsKey": {
        "ExcludeCodeNames": ["CMSHomePagePath"]
      }
    },
    "OptInFeatures": {
      "QuerySourceInstanceApi": {
        "Enabled": true,
        "Connections": [
          {
            "SourceInstanceUri": "http://localhost:60527",
            "Secret": "__your secret string__"
          }
        ]
      },
      "FieldMigrations": {
        "SourceDataType": "text",
        "TargetDataType": "assets",
        "SourceFormControl": "MediaSelectionControl",
        "TargetFormComponent": "Kentico.Administration.AssetSelector",
        "Actions": ["convert to asset"],
        "FieldNameRegex": ".*"
      }
    }
  }
}

Source instance API discovery

⚠️ Warning – source instance API discovery is only available when migrating from Kentico Xperience 13.

By default, JSON data storing the page builder content of pages and custom page templates is migrated directly without modifications. Within this content, page builder components (widgets, sections, etc.) with properties have their configuration based on Kentico Xperience 13 form components, which are assigned to the properties on the source instance. On the target Xperience by Kentico instance, the migrated data can work in the Page Builder's legacy compatibility mode.

However, we strongly recommend updating your codebase to the new Xperience by Kentico components. See Editing components in Xperience by Kentico to learn more.

To convert page builder data to a format suitable for the Xperience by Kentico components, the Kentico Migration Tool provides an advanced migration mode that utilizes API discovery on the source instance. The advanced mode currently provides the following data conversion:

Attachment selector properties - converted to a format suitable for the Xperience by Kentico Media selector component, with IEnumerable<AssetRelatedItem> values.
Page selector properties - converted to a format suitable for the Xperience by Kentico Page selector component, with IEnumerable<WebPageRelatedItem> values.

Prerequisites and Limitations

To use source instance API discovery, the live site application of your source instance must be running and available during the migration.
Using the advanced page builder data migration prevents the data from being used in the Page Builder's legacy compatibility mode. With this approach, you need to update all page builder component code files to the Xperience by Kentico format.
The source instance API discovery feature only processes component properties defined using [EditingComponent] attribute notation. Other implementations, such as properties edited via custom view components in the Razer view, are not supported.

public class MyWidgetProperties : IWidgetProperties
{
    // Supported
    [EditingComponent(PageSelector.IDENTIFIER, Label = "Selected products", Order = 1)]
    public IEnumerable<PageSelectorItem> SelectedProducts { get; set; } = new List<PageSelectorItem>();

    // NOT supported
    public IEnumerable<MediaFilesSelectorItem> Images { get; set; } = new List<MediaFilesSelectorItem>();
}

API discovery setup

Copy the ToolApiController.cs file to the Controllers folder in the live site project of your Kentico Xperience 13 source instance. Get the file from the following location in the Kentico Migration Tool repository:
- For .NET Core projects: KX13.Extensions\ToolApiController.cs
- For MVC 5 (.NET Framework 4.8) projects: KX13.NET48.Extensions\ToolApiController.NET48.cs

Register routes for the ToolApi controller's actions into the source instance's live site application.

For .NET Core projects, add endpoints in the project's Startup.cs or Program.cs file:

app.UseEndpoints(endpoints =>
{
    endpoints.MapControllerRoute(
        name: "ToolExtendedFeatures",
        pattern: "{controller}/{action}",
        constraints: new
        {
            controller = "ToolApi"
        }
    );

    // other routes ...
});

For MVC 5 projects, map the routes in your application's RouteCollection (e.g., in the /App_Start/RouteConfig.cs file):

public static void RegisterRoutes(RouteCollection routes)
{
    // Maps routes for Xperience handlers and enabled features
    routes.Kentico().MapRoutes()

    routes.MapRoute(
        name: "ToolExtendedFeatures",
        url: "{controller}/{action}",
        defaults: new { },
        constraints: new
        {
            controller = "ToolApi"
        }
    );

    // other routes ...
}

Edit ToolApiController.cs and set a value for the Secret constant:
```
private const string Secret = "__your secret string__";
```

Configure the Settings.OptInFeatures.QuerySourceInstanceApi configuration options for the Kentico Migration Tool:

"OptInFeatures":{
  "QuerySourceInstanceApi": {
    "Enabled": true,
    "Connections": [
      { "SourceInstanceUri": "http://localhost:60527", "Secret": "__your secret string__" }
    ]
  }
},

You can test the source instance API discovery by making a POST request to <source instance live site URI>/ToolApi/Test with { "secret":"__your secret string__" } in the body. If your setup is correct, the response should be: { "pong": true }

When you now migrate data, the tool performs API discovery of page builder component code on the source instance and advanced migration of page builder data.

Convert page types to reusable field schemas

It is not possible to migrate any page types that inherit fields from other page types. However, to make the manual migration of such page types easier, you can create reusable field schemas from specified parent page types. Specify a list of page types to be converted to reusable field schemas (separated with either ; or ,) in the Settings.CreateReusableFieldSchemaForClasses configuration option.

The following example specifies two page types from which reusable schemas are created:

"Settings":{
  ...

  "CreateReusableFieldSchemaForClasses": "Acme.SeoFields;Acme.ArticleFields"
},

⚠️ Notes

Conversion of page types to reusable field schemas works best when all field names of page types are unique (i.e., prefixed with the page type name). If multiple page types converted to reusable field schemas have fields with the same code name, the code name is prefixed with the content type name in the converted reusable field schemas.
Page types specified by this configuration option are also migrated as content types into to the target instance.

Convert text fields with media links

By default, page type and module class fields with the Text data type and the Media selection form control from the source instance are converted to plain Text fields in the target instance. You can instead configure the Kentico Migration Tool to convert these fields to the Content items data type and use the Content item selector form component, or Media files data type and use the Media file selector form component if you choose to convert attachments and media library files to media libraries instead of content item assets.

⚠️ Notes

Only media libraries using the Permanent file URL format are supported. Content from media libraries with enabled Use direct path for files in content setting will not be converted.

If you enable this feature, you also need to change retrieval and handling of affected files in your code, as the structure of the stored data changes from a text path to a Media files data type.

Source

~/getmedia/CCEAD0F0-E2BF-459B-814A-36699E5C773E/somefile.jpeg?width=300&height=100

Destination

[
  {
    "Identifier": "CCEAD0F0-E2BF-459B-814A-36699E5C773E",
    "Name": "somefile.jpeg",
    "Size": 11803,
    "Dimensions": { "Width": 300, "Height": 100 }
  }
]

The value of the field now needs to be retrieved as a media library file.
If the target instance is a SaaS project, you need to manually move content item asset files. See Content items for more information.

Convert to content item assets

To enable this feature, configure the OptInFeatures.CustomMigration.FieldMigrations options for this tool. Use the values in the code snippet below:

"OptInFeatures": {
  "CustomMigration": {
    "FieldMigrations": [
      {
        "SourceDataType": "text",
        "TargetDataType": "contentitemreference",
        "SourceFormControl": "MediaSelectionControl",
        "TargetFormComponent": "Kentico.Administration.ContentItemSelector",
        "Actions": [
          "convert to asset"
        ],
        "FieldNameRegex": ".*"
      }
    ]
  }
}

FieldNameRegex - a regular expression used to filter what fields are converted. Only fields with field names that match the regular expressions are converted. Use .* to match all fields.

Convert to media libraries

Attachment links (containing a getattachment handler) are migrated as attachments and changed to the Media files data type.
Media file links (containing a getmedia handler) are changed to the Media files data type. It is expected that the media library containing the targeted file has been migrated.

To enable this feature, configure the OptInFeatures.CustomMigration.FieldMigrations options for this tool. Use the values in the code snippet below:

"OptInFeatures":{
  "CustomMigration":{
    "FieldMigrations": [
      {
        "SourceDataType": "text",
        "TargetDataType": "assets",
        "SourceFormControl": "MediaSelectionControl",
        "TargetFormComponent": "Kentico.Administration.AssetSelector",
        "Actions": [ "convert to asset" ],
        "FieldNameRegex": ".*"
      }
    ]
  }
}

FieldNameRegex - a regular expression used to filter what fields are converted. Only fields with field names that match the regular expressions are converted. Use .* to match all fields.

Convert attachments and media library files to media libraries instead of content item assets

By default, media libraries and attachments are migrated as content item assets in the target instance, which is the recommended approach to ensure future-proofing of project and improve the content model. You can modify this behavior by configuring the value of the MigrateMediaToMediaLibrary setting to true and convert media library files and attachments to media libraries if you want to continue using media libraries. When set to false, media libraries and attachments are migrated as content item assets in the target instance.

Media libraries

In Xperience by Kentico, Media libraries are global instead of site-specific.
The code name of each media library on the target instance is {SiteName}_{LibraryCodeName}.
Media library permissions are currently not supported in Xperience by Kentico and are not migrated.

Attachments

Page attachments are migrated into a media library named: "Attachments for site <sitename>"
The media library contains folders matching the content tree structure for all pages with attachments (including empty folders for parent pages without attachments). The folders are named after the node alias of the source pages.
Each page's folder directly contains all unsorted attachments (files added on the Attachments tab in the source's Pages application).
Attachments stored in specific page fields are placed into subfolders, named in format: "__fieldname". These subfolders can include multiple files for fields of the Attachments type, or a single file for File type fields.
Any "floating" attachments without an associated page are migrated into the media library root folder.
The migration does not include temporary attachments (created when a file upload is not finished correctly). If any are present on the source instance, a warning is logged in the migration protocol.

The following is an example of a media library created by the Kentico Migration Tool for page attachments:

Articles (empty parent folder)
- Coffee-processing-techniques (contains any unsorted attachments of the '/Articles/Coffee-processing-techniques' page)
  - __Teaser (contains attachments stored in the page's 'Teaser' field)
- Which-brewing-fits-you
  - __Teaser
- ...

Additionally, any attachments placed into the content of migrated pages will no longer work in Xperience by Kentico. This includes images and file download links that use /getattachment and /getimage URLs.

If you wish to continue using these legacy attachment URLs from earlier product versions, you need to add a custom handler to your Xperience by Kentico project. See Migration.Toolkit.KXP.Extensions/README.MD for instructions.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

Migration CLI

Set up the source instance

Set up the target instance

Migrate data

Migrate command parameters

Examples

Migration details for specific object types

Content types

Reusable field schemas

Content items

Pages

Page builder content

Categories

Custom modules and classes

Custom tables

Media libraries

Attachments

Forms

Users

Members

Contacts

Configuration

Example

Source instance API discovery

Prerequisites and Limitations

API discovery setup

Convert page types to reusable field schemas

⚠️ Notes

Convert text fields with media links

⚠️ Notes

Convert to content item assets

Convert to media libraries

Convert attachments and media library files to media libraries instead of content item assets

Media libraries

Attachments

Files

README.md

Latest commit

History

README.md

File metadata and controls

Migration CLI

Set up the source instance

Set up the target instance

Migrate data

Migrate command parameters

Examples

Migration details for specific object types

Content types

Reusable field schemas

Content items

Pages

Page builder content

Categories

Custom modules and classes

Custom tables

Media libraries

Attachments

Forms

Users

Members

Contacts

Configuration

Example

Source instance API discovery

Prerequisites and Limitations

API discovery setup

Convert page types to reusable field schemas

⚠️ Notes

Convert text fields with media links

⚠️ Notes

Convert to content item assets

Convert to media libraries

Convert attachments and media library files to media libraries instead of content item assets

Media libraries

Attachments