What Kentico's Migration Tool Doesn't Move (KX13 → XbyK)

What Kentico's Migration Tool Doesn't Move (KX13 → XbyK)

The Kentico Migration Tool (KMT) handles a lot: sites, pages, content types, contacts, forms, media libraries. But it does not deliver a full product-to-product upgrade. It moves structured database records while leaving application code, custom admin UI, page ACLs, password hashes, cloud-hosted media binaries, and several content-model features either unsupported or only partially transformed.

This guide covers the tool's documented boundaries — what it skips, what it only partially handles, and the engineering work each gap creates. It is not about the KX13 end-of-support deadline or the broader replatform project (redesigning templates, rebuilding integrations, retraining editors). Those are separate efforts measured in months. The gaps below are scoped to data migration: what the KMT transfers, what it drops, and what your team does about each one.

Gap classification key used throughout this guide:

• 🔴 Blocker — must be resolved before running the KMT or the tool will fail / produce corrupt output
• 🟡 Pre-migration — should be resolved before the run to avoid post-migration cleanup debt
• 🟢 Post-migration — can be addressed after the KMT completes, but must be budgeted explicitly

What version of KX13 does the Migration Tool require?

The source must be Kentico Xperience 13 with Refresh 5 (hotfix 13.0.64) or newer. The KMT relies on specific fields in system classes introduced in that hotfix. Running it against an earlier build produces immediate database column errors. Apply Refresh 5 before touching any migration configuration.

🔴 Blocker: Portal Engine must be migrated to MVC before KMT runs. Any Portal Engine project must be rebuilt in ASP.NET Core MVC within KX13 first. This applies to hybrid configurations too — even a single Portal Engine template disqualifies the source for KMT. The Portal Engine → MVC conversion is a separate project requiring its own scoping, development, and QA cycle. Do not conflate it with the XbyK migration run.

Which content-model features does the tool not move correctly?

XbyK replaces deep, hierarchical content trees with reusable content items and a different field schema model. The KMT's translation between KX13's paradigms and XbyK's is incomplete in several documented areas.

Page type inheritance is unsupported 🟡 Pre-migration

Page type inheritance is the KX13 mechanism where one page type inherits fields from a parent page type. Xperience by Kentico does not support 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.

Every inheriting page type arrives in XbyK as a standalone content type with all fields flattened in. If you had a base type BasePage with SEO fields inherited by Article, Product, and Event, each of those three types will contain its own copy of every SEO field after migration. No shared schema. No single place to update them.

What to do about it: The KMT includes a CreateReusableFieldSchemaForClasses configuration option that designates a KX13 parent page type as a reusable field schema in XbyK. This must be configured before your migration run — it cannot be retroactively applied to already-migrated content types. Identify every page type where ClassInheritsFromClassID IS NOT NULL in CMS_Class and decide which become reusable field schemas versus standalone types.

Effort: For a site with 5–10 inheriting page types, expect 2–4 hours to audit the inheritance tree and configure CreateReusableFieldSchemaForClasses correctly.

Macros in field defaults and settings break 🟡 Pre-migration

Macro expressions in page type field default values or other settings are not evaluated or converted. The raw macro string migrates, but XbyK does not support macros in the same contexts KX13 did. After migration, any field that relied on a macro default — {% CurrentUser.UserName %}, {% CurrentDateTime %}, or a custom resolver macro — will display the literal macro text or silently produce an empty value.

What to do about it: Query CMS_FormUserControl and CMS_ClassField for values containing {% patterns. Replace macro defaults with static values before migration, or implement equivalent logic in XbyK using custom form components or event hooks (specifically IFormFieldValueProvider for computed defaults).

Field categories are dropped 🟢 Post-migration

Field categories — the named groupings that organize fields into collapsible sections within the KX13 editing form — are dropped during migration. Fields arrive in XbyK ungrouped. Field category definitions are stored in CMS_FormUserControl metadata and CMS_ClassField.FieldCaption; none of this structural metadata is carried forward.

This is a UI-only loss: no data is affected and no content is corrupted. But for content types with 20+ fields, editors will face a flat, unstructured form in the XbyK admin until categories are recreated manually.

What to do about it: Before migration, export your field category structure from the KX13 Form Builder (or query CMS_ClassField directly and filter by FieldOrder groupings). Use this as the specification for recreating field groupings in XbyK's UI form configuration after migration. Effort: Plan 30–60 minutes per complex content type.

Custom data types and form controls need auditing 🟡 Pre-migration

Field mapping between KX13 and XbyK is best-effort for standard types and undefined for custom ones. If your content model relies on custom form controls or non-standard data types, audit every migrated field definition before editors touch production content. Fields that cannot be mapped are either dropped or migrated as plain text without validation.

Check CMS_FormUserControl for any UserControlCodeName values that do not appear in XbyK's built-in control list. Each is a candidate for manual remediation.

Multi-language / culture-specific content behavior 🟡 Pre-migration

KX13 uses a culture-variant model where CMS_Document holds one row per page per culture. XbyK uses language variants attached to content items through a different schema. The KMT handles standard culture-to-language mapping, but non-standard locale codes, culture-specific URL patterns, and pages published in some cultures but not others require explicit validation post-migration.

What to do about it: Before migration, run a query against CMS_Document grouped by DocumentCulture to identify all active cultures and any pages with partial culture coverage. Verify that each culture code maps cleanly to an XbyK language variant. Pages that exist in the default culture but not in secondary cultures may be created as draft-only variants in XbyK — verify this against your content completion requirements.

What happens to linked pages, permissions, and checked-out content?

Linked pages become independent copies 🟡 Pre-migration

Linked pages in KX13 are references — a single page instance appearing in multiple locations in the content tree. Xperience by Kentico does not support linked pages. By default, the KMT creates standard page copies for any linked pages on the source instance.

If you had one About Us page linked into three site sections, you now have three independent copies. Edit one, and the other two go stale. Content duplication also inflates your page count and can cause duplicate-content SEO issues if canonical tags are not managed.

What to do about it: Audit linked pages before migration:

SELECT NodeID, NodeAlias, NodeLinkedNodeID, NodeSiteID
FROM CMS_Tree
WHERE NodeLinkedNodeID IS NOT NULL
ORDER BY NodeSiteID, NodeAlias

For each result, decide: redirect, content reference item, or genuine copy. For non-trivial cases, implement a custom ILinkedPageHandler in the KMT's extension pipeline. The interface signature is:

public interface ILinkedPageHandler
{
    Task<LinkedPageResult> HandleAsync(LinkedPageInfo linkedPage, CancellationToken cancellationToken);
}

Register your implementation in the KMT's DI container before the migration run. Without a custom handler, every linked page becomes a copy.

Page permissions and ACLs vanish 🟢 Post-migration (but must be budgeted)

Page permissions (ACLs) are not migrated into Xperience by Kentico. Because XbyK uses a different permission model, no existing role permissions or UI personalization settings are migrated. After migration, permissions for each role must be configured from scratch.

This is a complete reset. XbyK uses application-level permissions (read, create, modify, delete per module) rather than per-node ACL entries. There is no 1:1 mapping from CMS_ACL / CMS_ACLItem to XbyK's model.

What to do about it: Before migration, export your KX13 ACL configuration:

SELECT a.ACLID, t.NodeAliasPath, r.RoleName, ai.Allowed, ai.Denied
FROM CMS_ACL a
JOIN CMS_Tree t ON t.NodeACLID = a.ACLID
JOIN CMS_ACLItem ai ON ai.ACLID = a.ACLID
JOIN CMS_Role r ON r.RoleID = ai.RoleID
ORDER BY t.NodeAliasPath

Map each rule to XbyK's role-based permission model. Effort: 2–4 hours for sites with fewer than 10 roles and simple ACL structures; 2–5 days for large multi-editor environments with per-page granularity.

Checked-out pages are skipped 🔴 Blocker

The KMT processes published and latest draft versions — not the working copy held by the checked-out lock. If a page is checked out, the tool migrates the last published version, potentially skipping in-progress edits entirely.

What to do about it: Enforce a content freeze before your migration window. Identify and bulk check-in all outstanding pages:

SELECT DocumentID, DocumentName, DocumentCheckedOutByUserID, DocumentCheckedOutWhen
FROM CMS_Document
WHERE DocumentCheckedOutByUserID IS NOT NULL
ORDER BY DocumentCheckedOutWhen DESC

This can also be done via the Pages application mass-actions in KX13. Do not start a migration run until this query returns zero rows.

Scheduled tasks are out of scope 🟢 Post-migration

Scheduled tasks defined in KX13 (CMS_ScheduledTask) are application code, not data. The KMT does not migrate them. Every custom scheduled task — whether it runs database cleanup, generates reports, calls external APIs, or processes queued items — must be reimplemented in XbyK using IScheduledTaskExecutor. This includes built-in tasks you have modified.

What to do about it: Query CMS_ScheduledTask for all enabled tasks with custom TaskAssemblyName values. For each, document the schedule interval, execution logic, and dependencies. Plan these as development items in the application rebuild workstream.

Why media libraries and attachments fail

Extracting text is straightforward. Moving binary files is where migrations break, producing broken images and dead download links.

Cloud-stored media is invisible to the tool 🔴 Blocker

The migration tool reads media library files from the local file system only. If your source instance stores media files in Azure Blob Storage, Amazon S3, or any other remote storage backend, the tool cannot read files from those locations. This is one of the most commonly missed prerequisites.

Two options:

1. Download files locally first. Sync your cloud storage to the local filesystem path the KMT expects (typically ~/CMS/media/<sitename>/), then run the migration normally.
2. Migrate metadata only. Set MigrateOnlyMediaFileInfo to true in the KMT configuration — this migrates only the database records (Media_File rows) without the binary files. You then transfer the actual files to the target storage separately, matching by FileGUID.

Option 2 is cleaner for large media libraries (500+ GB), but content items in XbyK will have broken media references until the file transfer completes. Do not go live until both the metadata migration and the binary transfer are verified.

Filesystem-only attachments cannot be migrated 🔴 Blocker

KX13 supported storing page attachments either in the database (CMS_Attachment.AttachmentBinary) or on the filesystem. If your instance was configured with CMSStoreFilesInFileSystem = true and CMSStoreFilesInDatabase = false, those attachment binaries exist only on disk. The KMT reads attachment data from the database — it cannot read filesystem-only attachments.

Only attachments stored in the database are currently migrated.

What to do about it: Write a pre-migration script that reads filesystem attachments and inserts their binary content into CMS_Attachment.AttachmentBinary. This data-preparation step must complete before the KMT runs. Identify affected records with:

SELECT AttachmentID, AttachmentName, AttachmentSiteID
FROM CMS_Attachment
WHERE AttachmentBinary IS NULL

Legacy attachment URLs break in XbyK 🟢 Post-migration

Page attachments are not a native XbyK feature in the way they worked in KX13. Legacy links inside rich text fields that use /getattachment/{guid}/{filename} or /getimage/{guid}/{filename} URL patterns will return 404 in XbyK unless you add a custom route handler or rewrite the URLs.

What to do about it: Before migration, query CMS_Document.DocumentContent and CMS_Document.DocumentPageBuilderWidgets for the string /getattachment to quantify the scope. If the count is high, implement a URL rewriting middleware in XbyK that resolves legacy GUIDs to the new asset storage URLs. If the count is low, a content transformation script at migration time is faster.

Users, passwords, and marketing data

Passwords do not transfer 🟢 Post-migration (must be planned before go-live)

User passwords are not migrated. KX13 used ASP.NET Forms authentication with different security and hashing mechanisms than the ASP.NET Core Identity system used in XbyK. The hash formats are incompatible — there is no conversion path.

All users (including editors and customer users) will need to create new passwords using the invitation or password recovery flow.

What to do about it: For admin users and editors, use XbyK's invitation flow to send password-set emails before go-live. For live-site members, trigger a password recovery campaign or integrate with an external identity provider.

The migration event is a practical forcing function for introducing SSO: move basic profile data into an identity provider (Azure Active Directory B2C, Auth0, or Okta), with extended profile attributes going into XbyK member storage. If your site has more than a few hundred member accounts, plan this as a separate identity migration workstream — not an afterthought on launch day.

Email marketing data is not transferred 🟢 Post-migration

The Kentico Migration Tool does not transfer email marketing data. This covers:

• Email templates
• Campaign definitions
• Individual marketing emails
• Form autoresponders
• Subscriber and recipient lists

Email components (widgets and templates) from KX13 use a different format than XbyK's Email Builder. They require manual code adjustment, not just content copying.

What to do about it: Export your email templates as HTML from KX13 before migration. Reconstruct them in XbyK's Email Builder. Recipient lists can be rebuilt from migrated contacts and contact groups, but the association between contacts and email campaigns must be re-established manually. Budget this as a separate workstream — it is not a KMT configuration problem.

Application code, custom admin UI, and widgets

The KMT is strictly a database utility. It does not touch your codebase.

Application code is out of scope 🟢 Post-migration (largest workstream)

The KMT migrates data models and content only. Code migration is not supported. Code, customizations, and any unsupported content need to be manually transferred to the target Xperience by Kentico solution and adjusted for XbyK's architecture and API differences.

The KMT does not move controllers, views, repositories, custom API endpoints, scheduled tasks, event handlers, or any C# code. Your entire application codebase — routing, data access, integrations, front-end rendering — must be manually ported to XbyK's .NET 8 architecture.

This is the largest single workstream in any KX13 → XbyK project. The data migration the KMT performs can complete in days to weeks. The application rebuild is a separate project measured in months. Never conflate the two when estimating timelines or communicating with stakeholders.

Custom admin UI requires a React rewrite 🟢 Post-migration

The Xperience by Kentico Admin UI is built with React. Its interface is entirely based on modern JavaScript components. The old KX13 technology stack (Web Forms-based admin) is not compatible, so any custom Admin UI components created in KX13 — whether you extended existing controls or built your own — must be reimplemented in the new React-based framework.

UI elements related to custom tables (listings, filters, detail pages) are not migrated and need to be implemented from scratch. The administration of Xperience by Kentico uses a different technology stack than Kentico Xperience 13 and is incompatible at every layer.

Every custom listing page, form component, and module UI element built in KX13's Web Forms-based admin must be rebuilt using React and TypeScript with XbyK's Admin UI SDK.

What to do about it: Inventory every custom admin UI element in your KX13 project. Use CMS_UIElement to enumerate custom UI elements:

SELECT ElementID, ElementName, ElementDisplayName, ElementType
FROM CMS_UIElement
WHERE ElementResourceID IN (
    SELECT ResourceID FROM CMS_Resource WHERE ResourceIsInDevelopment = 1
)
ORDER BY ElementType, ElementName

Prioritize which elements are needed at launch versus which can be deferred. Teams coming from Web Forms should budget for the React/TypeScript learning curve — this is not a translate-line-by-line port.

Widgets: data migrates, code does not 🟢 Post-migration

The KMT migrates widget data — the JSON property values stored in DocumentPageBuilderWidgets — but not widget code. The architectural differences are significant:

The data migration preserves widget property values, so content is not lost. Kentico provides a legacy compatibility mode for migrated widget JSON, but recommends updating to native XbyK components for long-term support.

What to do about it: Use the KMT's IWidgetPropertyMigration extension point to transform property schemas that changed between versions. The interface allows you to map old property names to new ones during the migration run:

public interface IWidgetPropertyMigration
{
    string WidgetIdentifier { get; }
    Task<WidgetPropertyMigrationResult> MigratePropertiesAsync(
        JObject sourceProperties,
        CancellationToken cancellationToken);
}

Map each KX13 widget to its XbyK ViewComponent equivalent before the migration run. If you want native property-shape conversion rather than just preserving legacy JSON, keep the KX13 live site accessible during migration so the tool can use source-instance API discovery for widget metadata.

What commerce data can and cannot be migrated?

Kentico Migration Tool added support for migrating orders and customers in January 2026. Before that date, all commerce data was out of scope.

What migrates now:

• Customers — records and addresses, including custom fields defined on COM_Customer
• Orders — records, order items, order addresses, including custom fields

What does not migrate:

• SKUs. The KMT does not natively support migrating KX13 SKUs to XbyK. Product catalog data (prices, stock levels, product attributes stored in COM_SKU, COM_SKUOptionCategory, COM_VariantOptionCategory) must be migrated using custom class mappings or rebuilt in XbyK's Digital Commerce content types. Kentico published a guide for migrating page SKU data (May 2026) that requires custom code — it is not a configuration option.
• Multi-store. Xperience by Kentico does not have multistore support. If your KX13 instance runs multiple storefronts with separate product catalogs and checkout flows, there is no equivalent architecture in XbyK. Evaluate whether XbyK's channel architecture can approximate your setup, or plan for a headless commerce integration (Shopify, commercetools, BigCommerce, etc.).
• KX13-XbyK commerce bridge. The commerce bridge was introduced as a temporary solution to help projects transition before XbyK gained native commerce capabilities. Its repository is archived and read-only — source code, releases, and NuGet packages remain available, but the repository accepts no new issues or pull requests. Support will not be extended. Do not plan new projects around the bridge.
• Order statuses — must be created manually on the XbyK target and mapped via KMT configuration before the migration run.
• Shipping and payment methods — only display names carry over; functional configuration must be recreated.

What to do about it: For product catalogs, model your products as content types in XbyK and use custom migration logic to extract SKU data from COM_SKU and insert it into the appropriate content item structure. For multi-store scenarios, decide on your commerce architecture before scoping the migration — this is a design decision, not a KMT configuration problem.

KMT gap summary

How to plan around these gaps

The pattern across every gap is the same: the KMT moves structured data; everything else is your team's responsibility. A realistic migration plan separates into two workstreams:

1. Data migration — running the KMT iteratively, validating output, adjusting configuration. This typically completes in days to weeks depending on data volume and complexity. A 100,000-page site with standard content types runs in a different order of magnitude than a 10-page marketing site with heavy commerce customization.
2. Application rebuild — porting code, rebuilding admin UI, reimplementing integrations, reconfiguring permissions. This is measured in months and is scoped independently of the KMT.

Work through this sequence:

1. Hotfix and scope the source. Get onto KX13 13.0.64 (Refresh 5) or newer. Identify and scope any Portal Engine-to-MVC work separately.
2. Classify your gaps. Use the table above. Every 🔴 blocker must be resolved before the first KMT run. Every 🟡 pre-migration item should be resolved before the run to avoid post-migration cleanup that is harder to fix in place. Every 🟢 post-migration item needs a named owner and a delivery date in your project plan.
3. Inventory unsupported features. List inheriting page types (CMS_Class where ClassInheritsFromClassID IS NOT NULL), macro-driven defaults (CMS_ClassField where field default contains {%), linked pages (CMS_Tree where NodeLinkedNodeID IS NOT NULL), and custom form controls (CMS_FormUserControl with custom assembly references). These become named remediation items, not UAT surprises.
4. Normalize pages and binaries. Check in all pages. Download cloud-stored media locally or enable MigrateOnlyMediaFileInfo. Copy filesystem-only attachments into the database before the run.
5. Plan security, identity, and marketing rebuilds. Export ACLs. Prepare admin and member password-reset flows. Treat email templates, campaigns, and recipient lists as target-side rebuilds with their own delivery dates.
6. Budget rewrite work outside the tool. Custom admin UI in React, application code ported to .NET 8, widget modernization, scheduled task reimplementation, and custom SKU mappings each need a story-point estimate, not a hand-wave.
7. Run iterative migrations. The KMT supports multiple runs with update behavior. Use repeatable dry runs to resolve mapping issues incrementally before cutover, rather than solving everything in a single high-risk migration window.

Start scoping at least 3–4 months before any internal deadline. Discovering these gaps after committing to a launch date is the most common reason KX13 → XbyK projects stall.

Audit your KX13 instance against the gap table above before writing a single line of migration configuration. Know which gaps apply to your project, classify each as blocker / pre-migration / post-migration, and assign engineering time for each one.