Xperience by Kentico migration tool - migrating into an instance with existing content types

Hey Michael,

We've had a similar setup with a recent migration. There isn't great documentation that we found on this when we worked with the tool (it may have changed since the last migration). To use it out of the box without writing any code we found that everything was dependent on site and code names.

You can write custom handlers to map existing content types into new content types. We did this and it worked, however, not the most elegant thing to do. Our use case was we had some very odd namespace names, table names, etc. and we wanted to clean that up. So we mapped several content types into one and also did a one to one mapping with already created content items. In the Migration.Tool.Extensions/ClassMappings/ClassMappingSample.cs file there are some examples of mapping a content type one to one and many to one as well as a few other examples. I'd suggest taking a look there to help get started with this.

We use Kentico Migration Tool only as a starting point, as "just a boilerplate console application" for your migrations, that handles only very simple scenarious be default. The rest must be done via custom code anyway like Brenden said.

I'd say there's no (and shouldn't be!) any best practice for customizing migrator tool that should be limiting you. There's no "right" way of customizing it. Step-debug it, find the place where you need to apply some changes, and do it right there! Every migration project is unique, and the tool is designed to be flexibly bent however you need it.

So the workflow looks kinda like this:

1. Fork current Migration Tool code and add it to your XbyK project repo, then record all customizations there.
2. Important! Since these migration tool customizations will only live throughout the migration project don't bother writing high quality code and spend time on "proper" architecture. Whenever you see a place in "your" migrator code where you need a customization - go for it! Need to adjust one specific type, or field, or value, or subtree - doesn't matter.
3. Prepare to run migrations multiple (many!) times - script it start to finish including db restore
4. (Restore) and run the migration, even on non-empty destination to make sure it works more or less, and then..
5. Apply one customization to any part of the migrator tool, like, remap one type from 13 to another type in XbyK, since you have in migrator code intermediate DTO models available, you can do whatever with these objects - change guids, rename fields, change types, consolidate and so on.
6. Repeat steps #4 and #5 until you are done

Though this approach limits you in applying "updates" to migrator tool. Since it's gonna be heavily customized, when you try to update your fork with fresh migration tool code version you'll likely have conflicts. Therefore, update it only if there's value there, like releasing new previously not supported features. Otherwise, complete you migration on the version you started, and then apply the most recent refresh on top once the migration is complete.

Thanks Brendan and Dima for your responses, really appreciate you taking the time to share your experiences 👍

This is super helpful and very much aligns with what we’ve been seeing in practice.

Brendan, thanks for pointing out the ClassMappingSample examples. The confirmation that custom handlers are effectively the way forward (even if not the most elegant) is reassuring, and the reminder about code names being critical is a good callout. The many-to-one and one-to-one mappings are particularly relevant for us, as we’re also looking to modify some legacy structures during migration.

Dmitry, this is a great way of describing the XbyK migration tool as a flexible starting point rather than a finished solution. Treating it as a disposable, yet heavily customisable migration utility makes a lot of sense, especially the advice not to over engineer code that will only live for the duration of the migration.  And I agree on the iterative approach to repeat the steps and entire sequence until you get the migration spot-on.

Anyway, it’s good to have confirmation that there isn’t a hidden “official” way to do this and that modifying the tool to fit the project is, as we thought, the way to go.