---
title: Navigate advanced upgrades
---

> 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).

Upgrading from Kentico Xperience 13 (KX13) to Xperience by Kentico (XbyK) requires proper project structure, scenario planning, and effective use of AI tools.

This developer-focused resource covers how to structure upgrade repositories, match your scenarios to the right approach, and navigate topics like advanced data and code migration, optimization, and AI-assisted development.

> **Tip:** New to Xperience upgrades? Start with the [hands-on walkthrough](https://docs.kentico.com/guides/upgrade-to-xbyk/upgrade-walkthrough.md) first, then return here for advanced project structuring and scenario planning.

## Understand the migration tool repository

The [Kentico Migration Tool](https://github.com/Kentico/xperience-by-kentico-kentico-migration-tool) repository contains multiple projects. For customization work, you'll interact primarily with:

- **Migration.Tool.CLI/** - to [configure the tool](https://github.com/Kentico/xperience-by-kentico-kentico-migration-tool/blob/master/Migration.Tool.CLI/README.md#configuration) in `appsettings.json` and run the command-line executable
- **Migration.Tool.Extensions/** - to implement customization related to any content remodelling (e.g., mapping classes, transforming widgets, extracting reusable field schemas)
- **Migration.Tool.KX13.Extensions** or **Migration.Tool.KX13.NET48.Extensions** - to copy controllers from when configuring the Page Builder content migrations

The remaining projects (Core.KX13, KXP.Api, Common, etc.) provide either shared or version-specific migration logic that runs automatically. Generally, you don't need to modify these, with the exceptions of specific advanced scenarios (e.g., a custom command handler), and contributions to the tool's development (features/bug fixes).

> **Tip:** See the complete repository structure guide [in the GitHub documentation](https://github.com/Kentico/xperience-by-kentico-kentico-migration-tool/blob/master/docs/Repository-Structure.md).

## Use a three-repository approach

For data migration you need:

1. Your source instance
2. Your target Xperience by Kentico instance
3. A copy of the Kentico Migration Tool

We recommend you **use a three-repository approach** for upgrade projects with a clone of the migration tool repo **per project**.

```text title="Example repository structure"
Your-Upgrade-Reporitory/
├── kx13-source/              # 1. Source KX13 instance
│   └── (existing KX13 code - largely unchanged)
├── xbyk-target/              # 2. Target XbyK instance  
│   └── (new XbyK code - evolves iteratively)
└── migration-tool-custom/    # 3. Kentico Migration Tool (+ customizations)
    ├── Migration.Tool.CLI/
    │   └── appsettings.json
    ├── Migration.Tool.Extensions/
    │   ├── ClassMappings/
    │   ├── CommunityMigrations/
    │   └── WidgetMigrations/
    └── docs/
        ├── decisions.md
        └── scenarios.md
```

**Why a copy of the migration tool per project?**\
Each project needs unique migration tool customizations. Isolating the tool enables:

- Version control for migration logic
- Team collaboration on configurations
- Records of migration decisions
- Reusable patterns across migration runs

> **Tip:** [Git submodules](https://www.atlassian.com/git/tutorials/git-submodule) let you include one Git repository as a subdirectory of another, so you can work with all three repositories (source, target, migration tool) from a single parent repository while tracking each independently.

## Advanced upgrade tasks - decision tree

Most migrations require combining multiple strategies. Match your scenarios below to find the right approach and implementation guide.

> **Tip:** Missing guidance for your scenario? Use the **Send us feedback** button at the end of the page. We continuously add guides based on partner and client feedback.

Choose what you want to do:

- [Remodel content](#remodel-content)
- [Transform Page Builder widgets](#transform-page-builder-widgets)
- [Upgrade content retrieval code](#upgrade-content-retrieval-code)
- [Optimize media](#optimize-media)
- [Utilize AI to speed up data and code migration](#utilize-ai-to-speed-up-data-and-code-migration)
- [Get help and support](#get-help-and-support)

### Remodel content

#### Flatten the content tree

- Transform child page data...
  - into widgets on the parent page
    - see [Convert child pages to widget content](https://docs.kentico.com/guides/upgrade-to-xbyk/upgrade-deep-dives/convert-child-pages-to-widgets.md)
  - as reusable content items, referenced by widgets in parent page
    - choose the right strategy for your scenario, see [Migrate widget-collection relationships](https://docs.kentico.com/guides/upgrade-to-xbyk/upgrade-deep-dives/migrate-widget-collection-relationships.md) guide

#### Add structure to your data

- Restructure content types, create reusable schemas, consolidate fields
  - see [Remodel page types as reusable field schemas](https://docs.kentico.com/guides/upgrade-to-xbyk/upgrade-deep-dives/remodel-page-types-as-reusable-field-schemas.md) guide
- Extract widget data as reusable Content hub items
  - see [Migrate widget data as reusable content](https://docs.kentico.com/guides/upgrade-to-xbyk/upgrade-deep-dives/migrate-widget-data-to-content-hub.md) guide
- Accelerate remodeling with AI assistance
  - see [Speed up remodeling with AI](https://docs.kentico.com/guides/upgrade-to-xbyk/upgrade-deep-dives/speed-up-remodeling-with-ai.md) guide

#### Preserve content hierarchies

- Preserve content item hierarchies in Content hub
  - use **Custom directors**, see [Transfer parent-child page hierarchy to the Content hub](https://docs.kentico.com/guides/upgrade-to-xbyk/upgrade-deep-dives/transfer-page-hierarchy-to-content-hub.md) guide

### Transform Page Builder widgets

- Learn the basics about different strategies
  - see [Upgrade widgets from Kentico Xperience 13](https://docs.kentico.com/guides/upgrade-to-xbyk/upgrade-deep-dives/upgrade-widgets-introduction.md) guide
- Transform child page data into widgets on the parent page
  - see [Convert child pages to widget content](https://docs.kentico.com/guides/upgrade-to-xbyk/upgrade-deep-dives/convert-child-pages-to-widgets.md)
- Transform widget properties or change UI controls
  - see [Transform widget properties](https://docs.kentico.com/guides/upgrade-to-xbyk/upgrade-deep-dives/transform-widget-properties.md) guide
- Extract widget data as reusable Content hub items
  - see [Migrate widget data as reusable content](https://docs.kentico.com/guides/upgrade-to-xbyk/upgrade-deep-dives/migrate-widget-data-to-content-hub.md) guide

### Upgrade content retrieval code

- Migrate IPageRetriever, DocumentHelper, and TreeProvider code to XbyK APIs
  - see [Upgrade your content retrieval code](https://docs.kentico.com/guides/upgrade-to-xbyk/upgrade-deep-dives/upgrade-content-retrieval.md) guide

### Optimize media

- Optimize and compress images during migration
  - see [Optimize images during your upgrade](https://docs.kentico.com/guides/upgrade-to-xbyk/upgrade-deep-dives/optimize-images-during-upgrade.md) guide

### Utilize AI to speed up data and code migration

- Use pre-configured agent skills and best practices for KX13 migrations with **KentiCopilot**
  - see [KentiCopilot](https://docs.kentico.com/guides/development/kenticopilot.md)
- Leverage AI to expedite content migration
  - use the [KX13 content auditor](https://github.com/Kentico/xperience-by-kentico-kenticopilot/blob/main/plugins/kentico-kx13-migration/README.md#content-model-audit) to understand the structure of your content in KX13
  - use the [content migration skills](https://github.com/Kentico/xperience-by-kentico-kenticopilot/blob/main/plugins/kentico-kx13-migration/README.md#content-migration) to speed up migrating your KX13 content
- Accelerate content type remodeling with AI assistants
  - see [Speed up remodeling with AI](https://docs.kentico.com/guides/upgrade-to-xbyk/upgrade-deep-dives/speed-up-remodeling-with-ai.md) guide
- Speed up codebase migration with AI-assisted workflows for working with pages, widgets, and components
  - use [KX13 codebase migration skills](https://github.com/Kentico/xperience-by-kentico-kenticopilot/blob/main/plugins/kentico-kx13-migration/README.md#codebase-migration) for commonly used AI development tools (for example, GitHub Copilot or Claude)
- Leverage AI coding assistants with the context-rich [migration tool repository](https://github.com/Kentico/xperience-by-kentico-kentico-migration-tool)

### Get help and support

- Report migration tool bugs, errors, or unexpected behavior
  - use [GitHub issue tracker](https://github.com/Kentico/xperience-by-kentico-kentico-migration-tool/issues)
- Safely share database information when requesting help
  - use the [community Database anonymizer tool](https://github.com/kentico-ericd/xperience-community-database-anonymizer)