Upgrading Kentico 12 Portal to Kentico Xperience 13

Having started my career at Heartland Business Systems (“HBS”) almost a decade ago, I’ve had plenty of experience supporting customers as they have followed along Kentico’s upgrade path.  When Microsoft started to move away from Webforms, and sunset .Net 4.8 frameworks in favor of .Net Core, Kentico started its migration along with Microsoft, knowing if it didn’t keep pace, it would be left behind by faster technologies. Kentico Xperience 12 featured both Portal engine and MVC, and then finally Kentico Xperience 13 brought us into .Net Core support for the website. It's fast, new features are coming out frequently, and it’s the future. 

But many of our clients are left wondering “How can we upgrade?”.  Well sadly, the official answer from Kentico is you can’t upgrade from Kentico Xperience 12 Portal Engine to Kentico Xperience 13.  And I’m not just saying there’s no portal engine support, but you literally can’t upgrade the site.  To make matters worse, Portal Engine support is ending sometime in the end of 2023.  With large clients who have too much content to start over from the beginning, it was a bleak outlook, until now!

It’s a Bird!  It’s a Plane!  No, it’s the KX12 to 13 Converter! And It’s Free!

HBS is proud to present to the Kentico Community, the KX12 to 13 Converter.  This tool started out with two ideas:

1. Portal engine elements (templates, layout webparts, widgets) largely have similar elements in Page Builder (Templates, Sections, Widgets), so you should be able to map one to the other.
2. You can’t upgrade a KX12 Portal to KX13, but you can upgrade a KX12 MVC site to KX13, so if we can convert the KX12 Portal site to a KX12 MVC Site, we should be able to upgrade it.

And through much trial and error, comparing database structure between MVC and Portal, and a whole lot of brain melting code, the Converter was born! And as we do with all our Kentico tools, we offer it to everyone for free.

Wait, should I upgrade?

Before we dive into how the tool works, make sure you’ve asked the question “Why should I upgrade?”.  It’s very true that most sites will be better off starting from scratch: a fresh new site, new theme, on the latest technology.  Starting fresh also gives you an opportunity to refactor your code, optimize, and overall.  Besides, you must rebuild the website anyway since portal engine doesn’t exist in KX13.

However, many users have too much content that rebuilding would be near impossible.  Some of our clients have thousands of pages of content, both structured (Form or Content Tab) as well as unstructured (Widget zones), along with custom modules, Marketing data, etc. Upgrading to preserve that content for them is non-negotiable. 

If you need consultation and guidance on how to move forward for your organization, contact HBS as inquiry@hbs.net to schedule a discussion with me.

How it works

Portal Engine Converter

Both Portal engine and Page Builder have similar elements, structured differently.  The trick is mapping them.  The Portal Engine Converter scans to see what Templates, Layout Widgets, and Widgets are used, and then generates 4 configuration files for you:

1. Template Configuration: How to map Portal Engine Templates to your Page Builder Templates
2. Section Configuration: How Layout Widgets (such as Bootstrap Layout) map to Sections in Page Builder
3. Default Section Configuration: The default Section if a widget is not within a layout widget
4. Widget Configuration: How your Portal Engine Widget and it’s properties map to Page Builder Widgets

These configurations then also become your roadmap, helping you know what templates and widgets you need to create.  Keep in mind that you don’t need to have the templates, widgets, and the like created before you convert the document, but it’s good to create your gameplan and put in new field names, template code names, etc. (especially if you want to use modules like XperienceCommunity.PageTemplateUtilities which depend on naming conventions).

Worried you won’t get it right the first time? Fret not, there is a KX12 To 13 Receiver module for Kentico Xperience 13 that will allow you to re-push your conversions from your KX12 site to your upgraded KX13 instance.

Pre-Upgrade MVC Converter

When you’re ready to run an upgrade to KX13 (which should be done on a copy of the site), the Upgrade Operations in this module will guide you through getting your site MVC-ified.

1. Versioning and Workflow: It’s import during any upgrade to disable Version and Workflow, this helps you do that, and gives you options on how to handle pages that aren’t published, as well as clearing history.
2. Remove Classes: Portal Engine came with a lot of extra page types. This tool shows you which ones aren’t used so you can clean them up.
3. Convert Page Types: This tool helps you enable MVC Features for your page types and set things up for proper Url generation.
4. Convert Forms: You can’t upgrade if you have any Portal Engine Forms, the upgrade tool stops you. This helps convert your Forms to an MVC Form so you can keep all your data.
5. Site and DB Prep: This last step sets your site as MVC and fixes various database references that can cause SQL errors during the upgrade procedure.

Where to go from here

Remember, this tool upgrades your data and converts Portal Engine data to Page Builder Data, but it’s still up to you (or us 😉) to build out the site.  For longer projects, this usually will consist of an initial clone and upgrade, development work, and possibly a second clone and upgrade.  If you have questions, you can get in touch by requesting a call at inquiry@hbs.net.

Disclaimer: this is not the Kentico offcial and supported way of migrating from portal engine to MVC. In case of any issues with this approach, submit the issue directly to the KX12To13Converter GitHub repo