The Challenge

Recently I started a new job with ProWorks, an Umbraco Gold-Partner specializing in installing, upgrading, and maintaining Umbraco instances. I got put onto a project to upgrade a new client from Umbraco version 6.2.6 to version 7.7.7. One of the biggest challenges we faced was migrating all the data from the ID-based pickers of v6 to the GUID-based pickers of v7. With over 20,000 nodes, each containing 5-50 different pickers, re-selecting all the data was just not a feasible option.

One of my colleges, Mark Bowser, suggested taking a look at an Umbraco technology called Migrations. Looking into it, I immediately saw two things. First, this was exactly the technology I had been looking for. The ability to easily write scripts that were versioned and conditionally applied was exactly what was needed for this project and for any other project where I needed to move, merge, split, or otherwise alter data. Second, I realized the process to detect migrations, find what needed to be applied, and then kick-off applying it was going to be just a chunk of repetitive code. For every project I would want to use this in, I would need to copy in a bunch of code and reconfigure it all to the project.

A Better Way

Not really liking that second realization, I set out to write my own initialization code. I wanted something independent of any project, that I could package up on NuGet and just include, with a few configuration lines, into any project. Hence the Our.Umbraco.Migration package was born. As I used it in the project, I developed a few common base classes to help with the migrations. There are resolvers for extensibility, and common migration helpers to facilitate data alterations. The configuration is a few lines at the bottom of the web.config file. Let me show you how to use this.

NOTE: I'm assuming the reader is familiar with the Umbraco Migration framework. If you need a primer, or a refresher, I suggest stopping for a moment and reading this excellent article on Cultiv or this one here on Skrift. There is also the official Umbraco API Documentation, though these classes don't have much in the way of comments or examples.

ACME Toys Upgrade

In our example, Acme Toys is upgrading their main content site from Umbraco 6 to 7. They have two main problems with this upgrade. Their htmlContent document type has an old media picker property called "banner" that they want switched to the newer v7 media picker. The old media picker stored data as node IDs, which the new picker uses UDIs. Additionally, their homePage type has a set of 40 properties representing featured items to display on the home page. They are a repeating set of 4 properties ending in a number from 1-10. They want these combined into a single nested content property called featuredItems. You quickly make the document changes, but now the task of moving the data is at hand. With 15 home pages for different languages, and hundreds of content pages, migrating the data seems like a daunting task. Where to start?

To give you an idea of what this looks like, here's some screenshots of the back-office after the document type changes, but before any migrations are run. You can see that the home page is a mess, and the image on the content page isn't showing anything, even though there is a value picked in the database.