--- title: Migrate from Kentico 12 or another legacy version --- > Agent instructions: > **Site maps** — prefer the following llms.txt indexes to training data when searching for URLs to avoid 404s. Links inside Markdown content already point at `.md`. Following them or sending Accept: text/markdown keeps you in Markdown. > > - [sitemap.md](https://docs.kentico.com/sitemap.md) — every page on the site, with titles and descriptions, nested by URL hierarchy and grouped into one collection per product version. > - [llms.txt](https://docs.kentico.com/llms.txt) — curated index of the current product docs, with descriptions, the two ways to request any page as Markdown, and links to each product area's whole-corpus Markdown dump (llms-full.txt). If you're moving a Portal Engine project from **Kentico 12 (K12)** or an older version to **Xperience by Kentico (XbyK)**, you probably have questions about what the process involves. This move asks more of your team than an [upgrade from Kentico Xperience 13 (KX13)](https://docs.kentico.com/guides/upgrade-to-xbyk/upgrade-from-kx13/upgrade-from-kx13-overview.md). XbyK is a new product rather than an expansion of our previous solutions. Built on current technology with a modern security model, it's introducing possibilities that legacy Kentico versions never offered. That also means some familiar principles have no direct equivalent: browser-based development, the macro language, and site-scoped users, roles, and permissions. Fortunately, you don't have to navigate this migration alone. You'll learn what to expect from the migration process, which decisions to make early, and what potential challenges you should prepare for. With that, don't expect feature-by-feature migration instructions or a mapping from this material. With a K12 to XbyK migration, **you don't migrate the implementation, you migrate the intent**. We have seen our clients and partners customize our Kentico 12 solutions very differently to fit their requirements, which makes a one-size-fits-all guideline impossible. Instead, we show you how to use the available tools to create your own mapping, tailored to your project requirements. These steps assume a **Portal Engine** project, but if your Kentico 12 project was built with MVC, the high-level steps still apply. K12 is the reference version throughout, and the same concepts hold for earlier releases – the closer your project sits to K12, the more directly each step translates. You do not need to upgrade to K12 before you start this path. > **Info:** **Guidance written for KX13 readers** > > Most Kentico migration tooling and guidance assumes a KX13 source, so less of it applies directly to a K12 project. Read the [pages written for KX13 readers](https://docs.kentico.com/guides/upgrade-to-xbyk/upgrade-from-kx13.md) for the method rather than the specifics. ## Overview First, we'll look into [what changed between the products](#understand-what-changed), because those differences decide how you plan. The migration process you should plan for consists of four steps: 1. [Learn Xperience by Kentico](#learn-xperience-by-kentico) so your team knows the target before mapping anything onto it. 2. [Set up AI tools](#set-up-ai-tools), the tooling that carries the mechanical work. 3. [Analyze your project and create mapping](#analyze-your-project-and-create-mapping) together with your agent, then fine-tune the mapping by hand. 4. [Migrate iteratively](#migrate-iteratively) with KentiCopilot and the [Universal Migration Toolkit](https://docs.kentico.com/documentation/developers-and-admins/upgrade-to-xperience-by-kentico/migration-toolkit.md), one slice at a time, until the project is across. This will include content (pages, page types, categories, etc.), non-content data (users, roles, etc.), and source code. ![The three preparation steps, then the iterative migration loop](https://docs.kentico.com/docsassets/guides/migrate-from-kentico-12/migration-process.drawio.svg "The three preparation steps, then the iterative migration loop") > **Note:** **K12 to XbyK migration assumes an AI-assisted approach** > > We recommend using AI assistance throughout the migration process. While you can complete all steps manually, doing so will significantly increase the time and effort required. Decide which approach your team will take before estimating the project, as it can greatly affect the overall timeline. > **Tip:** **Alternative route: the Kentico Migration Tool** > > Kentico Migration Tool (KMT) moves structured content using predefined mapping, so it asks less of you, but reaches less far. We recommend the route described here, where you and your agent build the mapping. That way you build a content model optimized for Xperience by Kentico, rather than carrying over Kentico 12 patterns that require remodeling later. KMT is supported and worth trying, particularly for lift-and-shift migrations. However, its migration capabilities for K12 are more limited than for KX13. [Alternative route: the Kentico Migration Tool](#alternative-route-the-kentico-migration-tool) explains the trade-offs and costs of each approach. ## Understand what changed XbyK is not a newer version of the product your team knows. It is a next-generation platform that builds on the same Kentico DNA, but redesigned to take advantage of modern development patterns and workflows. Some things will feel familiar, while others require a fresh approach. Let's look at what that means in practical terms. ### The mindset shift On a K12 Portal Engine project, a lot of development happened in the browser. You built ASPX page templates, configured web parts, wrote transformations, and used macros, all through the administration interface. None of that exists in XbyK. Development happens in an IDE, like Visual Studio or VS Code, against a codebase, and reaches the server through a deployment. Deployments are code-driven too, usually through a CI/CD pipeline. In K12, a design change and a content change both happened in the browser. In XbyK, only the content change does. **Xperience by Kentico is code-first**, and that shifts who is responsible for what. Design, behavior, and performance optimization belong to developers. Editors work with content and [Page Builder](https://docs.kentico.com/documentation/developers-and-admins/development/builders/page-builder.md) without code access, which is deliberate and worth keeping. Administrators feel the change as well. K12 gave them prebuilt administration applications for a lot of everyday operations, including system settings, cache debugging, and built-in smart search configuration. XbyK does not ship these as ready-made administrative capabilities or workflows orchestrated from within the application UI. When your teams need them, developers build them to match your project's requirements. **XbyK is modular** where K12 was complete: instead of configuring an application that already contains everything (including features not needed for your domain), you add the pieces your project needs and extend them yourself. That moves work from configuration into implementation, and in return nothing you build waits for a product release. Third-party services release new features often, MCP servers among them, and an extensible project can start using such a feature as soon as it is available. Although XbyK builds on foundations your team already knows, the work is closer to re-platforming than upgrading – as is true for any move to a modern platform. The difference is that you are not starting from scratch and you are not starting alone: the decisions ahead are ones others have already faced. In the following sections, we'll take a closer look at the major shifts. ### Move away from macro-driven logic K12 macros let editors and developers put significant business logic directly into the administration through the browser. A macro in a web part property or a transformation could pull content, branch on a condition, or build a string. XbyK follows a different model and keeps business logic in code. Only two places still accept [macro expressions](https://docs.kentico.com/documentation/developers-and-admins/configuration/macro-expressions.md#macro-availability): email template source code, and default values for editing forms defined in the **Modules** application. As you migrate, focus on preserving the behavior your solution provides rather than recreating the macros that produced it. Some of what macros did has a direct home: - **Fields that appear only in certain situations** – [visibility conditions](https://docs.kentico.com/documentation/developers-and-admins/customization/extend-the-administration-interface/ui-form-components/ui-form-component-visibility-conditions.md) on form components. - **Validation** – a separate mechanism from visibility, through [validation rules](https://docs.kentico.com/documentation/developers-and-admins/customization/extend-the-administration-interface/ui-form-components/ui-form-component-validation-rules.md) rather than an expression typed into a field. - **Dynamic navigation** – modeled in the _Content hub_. See [Decide your content model](#decide-your-content-model). - **SEO and other computed values** – code, or the content model where the value belongs to the content itself. Everything else moves into code. Where a K12 macro determines how content is displayed, generated, or personalized, its recommended XbyK equivalent is usually a code-based component, such as a widget, view component, or page template. The logic lives in C#, where you can test it. Take the dynamic part out of the value someone typed in the UI, and put it where the rest of your logic lives. Content localization follows the same rule. K12 let you add resource strings through the administration interface. XbyK does not, so use a [resource file](https://docs.kentico.com/guides/development/multilingual/display-your-website-content-in-multiple-languages.md#translate-other-application-texts) or model the strings as content items. > **Note:** **Custom templating expressions** > > Building your own templating layer in XbyK is not a scenario we encourage. If your project genuinely cannot avoid one, read the [customization guidelines](https://docs.kentico.com/documentation/developers-and-admins/customization/stable-customization-guidelines.md#custom-templating-expressions) first. They describe how to keep custom expressions from conflicting with the product, not how to build the layer itself. Before planning any of this, find every macro your project actually uses. Macros turn up in places teams no longer remember configuring, which is why the audit comes first. We'll cover this in the [Audit your K12 project](#audit-your-k12-project) section. ### Decide how much freedom editors get K12 gave editors a wide reach into presentation. They pasted HTML into the rich text editor and into web parts built for exactly that, maintained whole stylesheets in a dedicated application, configured web parts, and wrote macros. XbyK removes these options by design. **Editors work with content and with the components developers built for them**, and anything beyond that is a feature someone has to implement. So editor freedom becomes a design decision, not a setting you turn on late in the project. Agree early on what each role may change, then build to that agreement. The choice shapes your content model, your widgets and your permissions at the same time. How much of a page belongs in Page Builder at all is the larger question behind this one. [Differences between Page Builder content and structured content](https://docs.kentico.com/guides/architecture/content-modeling/xperience-content-modeling-basics/differences-between-structured-content-and-page-builder-content.md) and [Meet business requirements with Page Builder](https://docs.kentico.com/guides/development/page-builder/meet-requirements-with-page-builder.md) work through the trade-offs with examples. > **Warning:** **Page Builder is permissive until you restrict it.** Every registered widget and section can be placed in any editable area unless you say otherwise, which gives editors more control over layout than most teams intend. Restrictions are set in code, per editable area and per widget zone, by listing the components you allow. See [Configure allowed components for editable areas](https://docs.kentico.com/documentation/developers-and-admins/development/builders/page-builder/create-pages-with-editable-areas.md#configure-allowed-components-for-editable-areas). Combine them with [role permissions](https://docs.kentico.com/documentation/developers-and-admins/configuration/users/role-management.md) and [page permissions](https://docs.kentico.com/documentation/developers-and-admins/configuration/users/role-management/page-permission-management.md) so the limits hold outside Page Builder as well. The [rich text editor](https://docs.kentico.com/documentation/developers-and-admins/configuration/rich-text-editor-configuration.md) is configured the same way: developers decide which formatting the toolbar offers. In-context editing also works differently. K12 editors changed pages on the live site, while XbyK editing happens in the administration interface, on the web page's **Page Builder** tab. Reviewers who have no administration account see the result through [shareable preview URLs](https://docs.kentico.com/documentation/developers-and-admins/configuration/shareable-preview-urls.md). **Tell your editors this early, because the workflow feels unfamiliar before it feels better.** The image below shows the editor experience in the XbyK **Page Builder** tab. ![The Page Builder tab of the Dancing Goat home page in XbyK, with a hero widget selected](https://docs.kentico.com/docsassets/guides/migrate-from-kentico-12/xbyk-pb.jpg "The Page Builder tab of the Dancing Goat home page in XbyK, with a hero widget selected") ### Map web parts, form controls, and presentation These tables pair concepts, not components, and no row is a like-for-like swap. The third column names what each pairing leaves behind, because that is where the work hides. On the website presentation side: | In K12 | In XbyK | What does not carry over | | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Web part | A [widget](https://docs.kentico.com/documentation/developers-and-admins/development/builders/page-builder/widgets-for-page-builder.md) or a .NET view component | Configuration in the browser. [Widget properties](https://docs.kentico.com/documentation/developers-and-admins/development/builders/page-builder/widgets-for-page-builder/widget-properties.md) are declared in code, and editors only fill them in. | | ASPX page template | A [page template](https://docs.kentico.com/documentation/developers-and-admins/development/builders/page-builder/page-templates-for-page-builder.md) | Building the template in the administration. XbyK page templates are registered in code, and editors choose from what exists. | | Form control with backend logic | A form component, with the logic in code | The single control that served both the administration and the live site. Visibility and validation are now [separate mechanisms](https://docs.kentico.com/documentation/developers-and-admins/development/builders/builder-component-properties-visibility-and-validation.md). | | Transformation | A Razor partial view, rendered for each item by the widget, page template, or view component that retrieves the list | Templates edited in the browser, and any macros or inline code inside them. The header, footer, alternating item and separator transformations become plain Razor loop logic. Formatting helpers move into the view model or Tag Helpers. Data comes from the component that renders the list, through the [content retrieval API](https://docs.kentico.com/documentation/developers-and-admins/development/content-retrieval/retrieve-page-content.md). | On the website content side: | In K12 | In XbyK | What does not carry over | | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Page type | A [content type](https://docs.kentico.com/documentation/developers-and-admins/development/content-types.md), page or reusable | The rule that every content item is a page with a URL. Reusable items live in the [Content hub](https://docs.kentico.com/documentation/business-users/content-hub.md) and appear wherever you use them. | | Media library | [Content item assets](https://docs.kentico.com/documentation/business-users/content-hub/content-item-assets.md) | XbyK has no media libraries. Files live in the _Content hub_ as assets on content items, so folders addressed by path give way to items you reference. | | Category | A [taxonomy](https://docs.kentico.com/documentation/developers-and-admins/configuration/taxonomies.md) | Categories tied to one site. A taxonomy is defined once and tags pages, emails, headless and reusable items alike. | | Content tree | A [website channel](https://docs.kentico.com/documentation/developers-and-admins/configuration/website-channel-management.md) plus the _Content hub_ | One tree that was structure, navigation and storage at once. Structure lives in the channel and content lives in the hub. | | Editable region | Nothing automatic | The page body that Portal Engine stored as one blob. Each region has to be mapped deliberately onto structured fields, rich text, or [widgets](https://docs.kentico.com/documentation/developers-and-admins/development/builders/page-builder/widgets-for-page-builder.md). | | Attachment | [Content item assets](https://docs.kentico.com/documentation/business-users/content-hub/content-item-assets.md) | Files bound to a single page. An asset belongs to a content item that anything can reference. | | Tag | A [taxonomy](https://docs.kentico.com/documentation/developers-and-admins/configuration/taxonomies.md) | Free-typed tags. A taxonomy's tags are defined before they are used. | | Page type inheritance | [Reusable field schemas](https://docs.kentico.com/documentation/developers-and-admins/development/content-types/reusable-field-schemas.md) | The parent-child chain. A schema is composed into a content type rather than inherited from above. | **Read both tables as starting points for a decision, not as a conversion recipe.** Nothing binds you to the pairings. If your web parts cluster into a few layouts, page templates may serve you better than one widget each. Some K12 features have no row at all, and [Audit your K12 project](#audit-your-k12-project) is where you find out which of yours do. ### Commerce Commerce is the area that changed most. XbyK [models a store differently](https://docs.kentico.com/guides/development/commerce.md), and features such as taxes, membership, e-products and invoices have no direct counterpart, so each one your store relies on becomes a decision about how to provide it rather than a thing to move. [Commerce features overview](https://docs.kentico.com/guides/upgrade-to-xbyk/upgrade-from-kx13/upgrade-commerce-features-overview.md) shows the current feature set to map onto. ### Digital marketing Your contact data has a place to land in XbyK, and the features K12 built on top of it land differently. Contact groups with a prebuilt set of conditions cover deterministic segmentation, A/B testing and web analytics come through integrations, and personas and lead scoring as K12 knew them are a custom build. Campaigns, automation, and email channels exist as well, in a shape designed for XbyK rather than carried across, so you need to decide what each one should do in XbyK rather than port its configuration. [Digital marketing](https://docs.kentico.com/documentation/business-users/digital-marketing.md) shows the current feature set to map onto. ## Learn Xperience by Kentico A K12 feature can only be mapped by someone who knows what XbyK offers in its place. That is why learning comes before analysis rather than after it. We see teams underestimate this step, and skipping it costs more later than it saves now. Budget time for learning, not only for moving the project across. Developers and business users need different starting points. **Developers** - [Xperience developer kickstart](https://docs.kentico.com/modules/developer-kickstart.md) – set up the environment, create content types, and get Page Builder running in one project. - [Content modeling](https://docs.kentico.com/modules/content-modeling-guide.md) – the thinking behind the content model you migrate into. - [Developer learning map](https://docs.kentico.com/guides/development/developer-learning-map.md) – the rest of the training modules, in order. **Editors and marketers** - [Content management essentials](https://docs.kentico.com/modules/content-management-essentials.md) – how content is created, edited and published in XbyK. - [User management essentials](https://docs.kentico.com/modules/user-management-essentials.md) – accounts, roles, and permissions, which work differently from K12. - [Business user learning map](https://docs.kentico.com/guides/digital-marketing/business-user-learning-map.md) – the rest of the path for business users. The [Documentation MCP server](https://docs.kentico.com/documentation/developers-and-admins/installation/mcp-server.md) supports this step. It needs no target instance, so your team can ask it questions about XbyK while the project still runs on K12. ## Set up AI tools The analysis, the mapping and the migration all run through an agent, so [KentiCopilot](https://docs.kentico.com/guides/development/kenticopilot.md) and the tooling around it have to be in place before any of that work starts. It matters which tool does what. KentiCopilot knows XbyK, so it proposes the target model and builds in your new project. It does not read K12: nothing in it corresponds to the K12 database reader that the upgrade plugin gives KX13 projects. Reading your K12 project is your agent's own work, done against the source, the administration interface and the database, and the K12 documentation is what teaches it what it is looking at. For many organizations, a security review comes first. [KentiCopilot security](https://docs.kentico.com/guides/development/kenticopilot/kenticopilot-security.md) describes where your project data travels, what each component retains, and which controls you configure yourself. Run the same review over the rest of the toolchain. The agent you work in, the model provider behind it, and every MCP server you connect each come with their own data handling and their own settings to configure. Do not limit your team to Kentico tools. Where your agent reads the K12 database directly, something like Microsoft's [SQL MCP Server](https://learn.microsoft.com/en-us/azure/data-api-builder/mcp/overview) puts that database behind entities and roles you define, so you decide what the agent sees. This matters most when you [map your non-content data](#map-your-non-content-data). Not all of it has to be in place at once. The [Documentation MCP server](https://docs.kentico.com/documentation/developers-and-admins/installation/mcp-server.md) needs no target instance, so it helps from the start. The [Management MCP server](https://docs.kentico.com/documentation/developers-and-admins/api/management-api/configure-management-mcp-server.md) connects to your target XbyK instance, and is how the agent writes content into it. The [web development plugin](https://github.com/Kentico/xperience-by-kentico-kenticopilot/tree/main/plugins/kentico-web-development) is what the agent works with inside your XbyK codebase, so it earns its place when the agent starts building in your XbyK project. > **Note:** **Check what the MCP server covers today** > > The Management MCP server works with content and the objects around it rather than the whole product, so expect parts of your migration to sit outside its reach. Its tool surface also grows release by release, which is why this material does not list it. See [the tools it exposes](https://docs.kentico.com/documentation/developers-and-admins/api/management-api/configure-management-mcp-server.md#limit-the-available-tools) before you plan around it. [Build a website with KentiCopilot](https://docs.kentico.com/guides/development/developer-kickstart/build-a-website-with-kenticopilot.md) lists the prerequisites and walks the setup, including the plugin's `agentify` readiness audit, which checks your project has the agent instructions and configuration it expects. [Work effectively with KentiCopilot](https://docs.kentico.com/guides/development/kenticopilot/work-effectively-with-kenticopilot.md) covers the habits that keep it useful over a long project. ## Analyze your project and create mapping Your agent reads the K12 project, and KentiCopilot proposes where what it found could land in XbyK. What you hand KentiCopilot is that audit, not your K12 database. What comes back is a starting point rather than an answer. You review it, correct it, and decide what the target actually looks like. Everything after this step carries out those decisions. > **Tip:** **Use the most capable model you have access to** > > Reading an unfamiliar K12 project and proposing a target model is broad, open-ended work, and that is where stronger models need the least direction. See [Choose a model that fits the task](https://docs.kentico.com/guides/development/kenticopilot/work-effectively-with-kenticopilot.md#choose-a-model-that-fits-the-task) for guidance on how to judge it. ### Audit your K12 project Start with an audit of the K12 side. You are looking for the things that behave differently in XbyK, not for a complete catalog of your project. - Page types and their fields. - Macro usage across the whole solution, which the K12 [macro report](https://docs.kentico.com/k12sp/macro-expressions/troubleshooting-macros/searching-for-macros.md) lists by object type and field. - Web parts and the custom code behind them. - Form controls that carry logic. - HTML and CSS written by editors. - Navigation that is generated at runtime. - Per-site users, roles, and permissions. - Contacts and marketing data. - Commerce objects. - Custom tables. - Administration customizations, which have to be rebuilt as React UI components. The `UIElement` table lists them, and projects that followed the recommended approach prefixed their classes. Point your agent at the [Kentico 12 documentation](https://docs.kentico.com/k12sp.md) before you ask it to read your project. Models know far less about Portal Engine than about current .NET, and an agent that cannot recognize a web part or an editable region will miss them in your source. Have it explore and plan before it reports anything, as [Work effectively with KentiCopilot](https://docs.kentico.com/guides/development/kenticopilot/work-effectively-with-kenticopilot.md#explore-then-plan-then-code) describes. An agent can do most of this reading for you if you point it at the source. Run the [macro report](https://docs.kentico.com/k12sp/macro-expressions/troubleshooting-macros/searching-for-macros.md) yourself first and hand the agent its output: the report already knows every object type and field that holds a macro, so letting an agent search for them instead costs tokens and finds less. Read the database alongside the source rather than instead of it. Pull the K12 schema through a SQL MCP server and have the agent tag which tables belong to which area – content, contacts, commerce, custom tables – and you get the volumes and relationships that reading source never produces. The schema does not replace the audit: it holds web part configuration as XML in a column, not as behavior anyone can read. These are the items worth checking explicitly: macros stored inside content, fields whose visibility depends on other fields, per-site users and permissions, page-level permissions, contacts, and commerce data, editor-authored HTML and CSS, form controls with custom logic, runtime-generated navigation, editing done on the live site, custom tables, tags, and URL aliases. Each one is quiet in the source project and expensive once the migration is underway. One deserves singling out. **Editable-region content** is the page body on most Portal Engine sites, and nothing moves it automatically. > **Warning:** **Scope what the agent reads** > > An agent reading your K12 database sends what it reads – contacts and orders included – to your model provider. Kentico ships no tooling for reading a K12 database, so no Kentico documentation describes where that data travels. This is the part of the review in [Set up AI tools](#set-up-ai-tools) that rests entirely on the tools you picked yourself. > > **Decide what the agent may reach before you point it at the database, and expect it to work around a missing tool** rather than stop at it. Where no MCP tool reaches the data it was asked for, capable models write their own SQL queries or scripts to read the database directly. Instruct your agent against it, and review every script it writes before you let it run. Some of the biggest migration challenges stem from features that have no direct counterpart in XbyK, or whose equivalent follows a different pattern. Most have a viable route forward, but the approach you choose affects the scope, effort, and cost. Make those decisions early so they can be properly reflected in your migration plan and budget. For everything that changed along the way, see [Upgrading to Xperience 13](https://docs.kentico.com/13/installation/upgrading-to-xperience-13.md#upgrade-overview) and the [technical comparison](https://docs.kentico.com/documentation/developers-and-admins/upgrade-to-xperience-by-kentico.md#technical-comparison) of KX13 and XbyK. The ones that most often shape a K12 migration include: - **Reporting** – built to your requirements rather than configured. A developer implements what your project reports on today. - **Integration bus** – integrations run through an external messaging service instead. XbyK publishes and consumes messages for business events such as form submissions and content publication. See [Integrate with decoupled systems](https://docs.kentico.com/documentation/developers-and-admins/integrate-with-decoupled-systems.md). - **Content staging** – [Content sync](https://docs.kentico.com/documentation/business-users/content-sync.md) moves content between environments. Its primary purpose is one-directional content operations, so it does not cover everything that staging did. - **Localization application** – resource strings live in a resource file or in the content model. [Move away from macro-driven logic](#move-away-from-macro-driven-logic) covers where each kind goes. - **Custom tables** – [custom module classes](https://docs.kentico.com/documentation/developers-and-admins/customization/object-types.md#define-the-data-class) hold structured data instead, with a different design behind them. - **On-site editing** – editing moves into the administration interface. [Decide how much freedom editors get](#decide-how-much-freedom-editors-get) describes what changes for your editors. - **Advanced marketing automation** – implemented per project, usually by your partner. - **Commerce** – a different shape from K12 commerce, as [Commerce](#commerce) describes. ### Decide your content model Have your agent propose a target model from what it read, either designing a new one or mapping your existing structures onto XbyK ones. Before you move any content to the suggested content model, verify it supports all scenarios required by the editor and marketing team. > **Tip:** Use the [Content Modeling MCP Server](https://docs.kentico.com/guides/architecture/content-modeling/content-modeling-mcp.md) to prototype the model and visualize it for stakeholders before you commit. Use the KentiCopilot Management MCP server to create the content types and their visibility conditions, then migrate a few pages of each type and confirm they behave the way editors need. Expect to iterate on those samples: restore the CI repository, fix the model, run again. Once a type is settled, have the agent write the bulk migration rather than carry it out. You pay for every page the agent handles itself, while a script costs the same whether it moves ten pages or ten thousand. The [Universal Migration Toolkit](https://docs.kentico.com/documentation/developers-and-admins/upgrade-to-xperience-by-kentico/migration-toolkit.md) is what moves structures and content in bulk, and [Migrate iteratively](#migrate-iteratively) covers how to drive it. Decide your navigation separately. In K12 a menu usually fell out of the content tree, through page menu properties and a menu web part. XbyK does not derive one for you, so navigation becomes a modeling decision. [Model website navigation](https://docs.kentico.com/guides/architecture/content-modeling/model-website-content-types/model-website-navigation.md#three-approaches-to-modeling-navigation-in-xperience-by-kentico) sets out three approaches, and defining it in the content tree stays closest to what your team already does. ### Map your non-content data Map your access model separately from the content model. Users, roles, and permissions require different design decisions and are best analyzed on their own. For AI-assisted migrations, consider reviewing access control in a dedicated session or assigning it to a separate agent before you consolidate the results into your migration plan. > **Key:** XbyK splits the single K12 user store in two: [users](https://docs.kentico.com/documentation/developers-and-admins/configuration/users.md) sign in to the administration, [members](https://docs.kentico.com/documentation/business-users/members.md) sign in to your website. Users are also not site-specific, so site-scoped roles, document-level ACLs and global administrators have no direct counterpart in a model built on global users and [workspaces](https://docs.kentico.com/documentation/developers-and-admins/configuration/users/role-management/workspaces.md). Bridging that difference is a design task, not a data-transfer task. This path moves no users, roles or permissions, so budget for designing your own access model and the process that populates it. Work out what each K12 role was really protecting, then express it with users, [roles](https://docs.kentico.com/documentation/developers-and-admins/configuration/users/role-management.md), members, and workspaces. The goal is not to recreate the old access model, but to design one that fits XbyK's capabilities and the way your teams work today. > **Note:** **Contacts, marketing data and commerce are not content** > > Nothing reads them out of your K12 project for you. The [Universal Migration Toolkit](https://docs.kentico.com/documentation/developers-and-admins/upgrade-to-xperience-by-kentico/migration-toolkit.md) does model commerce objects such as customers, orders and shopping carts, so there the work is the export and the mapping rather than the import. Contacts and marketing data have no import model, so they need custom modules on the code side and a data import of their own. Work the mapping out against sample data before you run anything over production records. ### Record the decisions Once the modeling decisions are made, write them down. Your agent needs them on disk rather than remembered from a conversation. Add them to the instructions your project already carries from setting up the `kentico-web-development` plugin, and record what maps to what and which K12 habits must not transfer to XbyK during migration. See [Build a website with KentiCopilot](https://docs.kentico.com/guides/development/developer-kickstart/build-a-website-with-kenticopilot.md) for how to write instruction files. ## Migrate iteratively You have a mapping and a briefed agent. What remains is a loop: pick a slice, migrate it, verify it, store it, take the next one. **Stand up the [Universal Migration Toolkit](https://docs.kentico.com/documentation/developers-and-admins/upgrade-to-xperience-by-kentico/migration-toolkit.md) before the loop starts.** It is a library rather than an AI tool, and pointing your agent at it is usually enough to get it running. Have your agent import through it rather than creating objects one at a time. The agent generates the data structures and imports them in a single pass, which is how this path is designed to work. Driving the Management MCP server object by object does the same job, but its tools return verbose results and every call consumes context, so a large slice burns tokens and compacts the session early. **Name the tool in your prompt.** Left to itself, an agent picks whichever tool it judges best, which may not be the one you want for a slice of this size. Its choice is sometimes the right one, so the point is not to forbid it but to decide deliberately where you hand that judgment over. **How you slice the work is your call.** You can cut by object type, taking one content type at a time, then users, then categories. You can also cut by what appears on the site, migrating a subtree of pages or one feature at a time. The second makes progress visible, because your target solution fills in as you go. **Keep each slice small enough** to verify before you start the next one. [Build a website with KentiCopilot](https://docs.kentico.com/guides/development/developer-kickstart/build-a-website-with-kenticopilot.md#work-in-slices-and-verify-each-one) covers how to size a slice and what to check before moving on. **Store to the [CI repository](https://docs.kentico.com/documentation/developers-and-admins/ci-cd/continuous-integration.md) once a slice is verified.** That becomes the point you restore to when a later slice goes wrong, so a failure costs you one slice rather than the whole run. > **Note:** **Two limits of UMT imports** > > Expect to re-run an import, and know what can block it. If anyone opens a migrated page in the administration interface, XbyK saves a draft of that page, and re-importing it fails until the draft is discarded. Keep the target instance closed to editors until a slice is signed off. > > The second limit is quieter. UMT writes straight to the database, so it skips the validation the administration interface applies. Content that imported without error can still fail those checks later, when someone works with it in the UI. **Inside a slice, content and code move together.** The agent creates the content types, ports the code that renders them, and moves the content itself. Non-content data gets its own passes, because users, contacts and data protection are not tied to any one page. One ordering holds inside every slice: the content type exists before any content lands in it. That is a step in the loop, not a gate you clear once for the whole project. ### Content Content is the category with the strongest tooling support, so you won't be starting from a blank page. Pages, media, and categories become content types and items in the _Content hub_. ### Non-content data Non-content data surprises teams coming from a KX13 upgrade, where there is barely any. From K12 it is a full third of the work, so plan it from day one rather than treating it as a tail end. The decisions are mostly one-time ones. The remaining data areas each have a starting point in the documentation: - **Users and roles** – [Users](https://docs.kentico.com/documentation/developers-and-admins/configuration/users.md), [Role management](https://docs.kentico.com/documentation/developers-and-admins/configuration/users/role-management.md) and [Workspaces](https://docs.kentico.com/documentation/developers-and-admins/configuration/users/role-management/workspaces.md). - **Contacts and activities** – [Contact management](https://docs.kentico.com/documentation/business-users/digital-marketing/contact-management.md). - **Data protection** – [Data protection](https://docs.kentico.com/documentation/developers-and-admins/data-protection.md). - **Commerce** – [Commerce features overview](https://docs.kentico.com/guides/upgrade-to-xbyk/upgrade-from-kx13/upgrade-commerce-features-overview.md), written for KX13 readers but accurate about what XbyK does and does not offer. Use your agent here too. It reads a K12 database schema faster than you do, and the mapping questions it raises are usually the ones worth answering first. Scope what it reaches before you point it at contacts or orders, as [Set up AI tools](#set-up-ai-tools) describes. > **Key:** The agent needs the shape of your data, not the records themselves. Work from the schema, and anonymize or sample anything you hand it from tables that hold personal data. ### Code Traditionally, code migration would be a third workstream to plan, estimate, and staff alongside content and configuration. With AI-assisted migration, that separation becomes much less pronounced. The agent generates code as part of the same migration passes that create your content model and move your data. As new content types are introduced, the code needed to render them is created alongside them. When migrated data requires custom functionality, the corresponding modules and integrations can be generated as part of the same process. The result is that each completed slice represents a working part of your future XbyK site, rather than migrated data waiting for a front end to be built around it. This incremental approach allows you to easily validate progress and reduces the amount of disconnected work that typically accumulates during a traditional migration. > **Note:** **Custom components are slices of their own** > > The Universal Migration Toolkit imports data. It does not rebuild the code behind that data, so a form control with its own logic, a custom field type, or a module your project added does not arrive with the records that use it. Each one is a port in its own right. Sequence them ahead of the content that depends on them, the same way a content type has to exist before content lands in it. [Migrate your code with KentiCopilot](https://docs.kentico.com/guides/upgrade-to-xbyk/assisted-upgrades/kenticopilot-code-migration-overview.md) explains the overall approach, while [KentiCopilot code migration - best practices](https://docs.kentico.com/guides/upgrade-to-xbyk/assisted-upgrades/kenticopilot-code-migration-best-practices.md) covers the habits and workflows that keep a long code migration on track. Both are written for KX13 sources, so read them for the method rather than the exact steps for K12. ## Alternative route: the Kentico Migration Tool _Kentico Migration Tool (KMT)_ and the _Universal Migration Toolkit (UMT)_ are two ways of moving structured content into XbyK, and they differ in where the mapping comes from. - [KMT](https://github.com/Kentico/xperience-by-kentico-kentico-migration-tool) knows Kentico shapes, so it arrives with a mapping built in and is bounded by what it models. - [UMT](https://github.com/Kentico/xperience-by-kentico-universal-migration-tool) is a general-purpose library for importing data into XbyK from any source. It takes whatever mapping you and your agent produce, which is why it reaches content KMT cannot. KMT is built on top of UMT, so the two combine: let KMT move what it models, and use UMT for whatever it leaves behind. See [Migration Toolkit](https://docs.kentico.com/documentation/developers-and-admins/upgrade-to-xperience-by-kentico/migration-toolkit.md) to learn how they relate. Either way you need to understand your K12 project: the UMT route uses that understanding to build the mapping up front, while KMT needs it to choose what to exclude and to remodel afterwards. > **Warning:** KMT creates content types that mirror your K12 page types, plus `Legacy.*` types for attachments and media. That is a lossy copy of your old model rather than a model designed for XbyK. > > The structured fields of your page types arrive, but the page body does not: Portal Engine stores editable-region and web part content as XML, and XbyK expects Page Builder JSON. > > Page type inheritance comes across flattened, and you get artifacts you did not ask for, such as transformation-holder classes as empty content types. > > Plan the remodeling and the presentation rebuild that have to happen on top of it. Choosing KMT changes more than how content moves. Learning XbyK still comes first, but the migration process is different. Instead of designing your target model up front and migrating in slices, you configure the tool, run the migration, and then address the gaps. That typically means remodeling parts of the solution and rebuilding functionality the tool could not transfer. The [KX13 upgrade guides](https://docs.kentico.com/guides/upgrade-to-xbyk/upgrade-from-kx13.md) describe this approach from planning through post-migration adjustments. Although they target KX13 projects, they are useful here as a process guide rather than a source of implementation details. Kentico Migration Tool is open source and customizable, and its [customization guide](https://github.com/Kentico/xperience-by-kentico-kentico-migration-tool/blob/master/docs/Customization-Guide.md) sets no limit on the source version. Some of that surface is KX13-specific though: widget migration and the Page Builder JSON transforms only apply to KX13 sources, which have Page Builder content to transform. When we ran KMT against a K12 project with its default configuration, editable-region content, page templates, web parts, tags and document aliases did not come across, though custom URL paths did. The [Kentico Migration Tool](https://github.com/Kentico/xperience-by-kentico-kentico-migration-tool) (KMT) supports Kentico 12 Portal Engine as a source from hotfix 12.0.20 upwards. Below that it refuses to run, so check your hotfix level before you plan around it. It moves structured data only. Page Builder content never enters the picture, because Portal Engine has none. ### What KMT moves - The content tree and page names. - Page type fields. - Custom URL paths. - Attachments, which become _Content hub_ assets. - Categories, which become a taxonomy. - Custom tables, which become [custom module classes](https://docs.kentico.com/documentation/developers-and-admins/customization/object-types.md) along with their data. - Forms and their submissions, though forms with file-upload fields can fail. ### What KMT leaves behind These are the things a generic mapping cannot decide for you, rather than gaps in the tool. - Editable-region content, which is the page body text on most Portal Engine sites. - Page templates, web parts and all other presentation. - Tags, URL aliases and page-level permissions. - Most settings. - Page type inheritance, which arrives flattened. ### Non-content data Users at Editor privilege and above arrive, as do members and any role that has members, with their memberships intact. What does not arrive is everything that governs access: permissions, site scope, workspace access and passwords. Only K12 global administrators end up with access to the administration. In short: you get accounts, not access. Contacts and activities migrate as a bulk copy. Customers and orders do not migrate from a Kentico 12 source. Do not take the success of the content migration as evidence that the rest of the solution has been migrated. Many Kentico 12 features, customizations, and integrations fall outside the capabilities of the migration tool. Review the [Upgrading to Xperience 13](https://docs.kentico.com/13/installation/upgrading-to-xperience-13.md) documentation and compare it against your own implementation before committing to an approach. The rule is simple: if a capability is important enough to appear on a project diagram, checklist, or requirements document, verify how it will be handled in XbyK. Assume nothing, validate everything. ### Plan for the run itself > **Key:** The pages step reads the entire attachment table regardless of what you exclude from the migration. On a site with a large attachment store this takes hours rather than minutes, and large contact volumes behave the same way. Schedule accordingly, and do not size the work from a trial run against a small database. The [repository](https://github.com/Kentico/xperience-by-kentico-kentico-migration-tool) contains the operational details of the migration tool, including the [usage guide](https://github.com/Kentico/xperience-by-kentico-kentico-migration-tool/blob/master/docs/Usage-Guide.md), [supported data types](https://github.com/Kentico/xperience-by-kentico-kentico-migration-tool/blob/master/docs/Supported-Data.md), and the [CLI reference and configuration options](https://github.com/Kentico/xperience-by-kentico-kentico-migration-tool/blob/master/Migration.Tool.CLI/README.md) for large migration runs. KMT is customizable, and developers can add project-specific logic at different stages of the migration pipeline. Test what it does with your own project before you plan around that. ## What's next? **The heavy lifting in this migration is the deciding, not the doing.** Learn how XbyK works, settle what maps to what, and agree it with the people who own the content, the code and the site's navigation. Only then hand the execution to your agent. KentiCopilot moves fast once those decisions are made, and it moves just as fast in the wrong direction when they are not. Where to go from here: - **Choosing your route?** We recommend the route described here, though KMT is supported and suits some projects. [Alternative route: the Kentico Migration Tool](#alternative-route-the-kentico-migration-tool) sets out what it costs and saves, and how the plan differs if you take it. - **Start learning XbyK** – the [Developer learning map](https://docs.kentico.com/guides/development/developer-learning-map.md) for developers, the [Business user learning map](https://docs.kentico.com/guides/digital-marketing/business-user-learning-map.md) for editors and marketers. - **Set up your tooling** – [KentiCopilot](https://docs.kentico.com/guides/development/kenticopilot.md) is the entry point. - **Ask your account executive** to connect you with partners who have made this move.