Building a custom migration in Drupal 8, Part 1: Getting started


Unlike previous versions, there’s no real way to “upgrade” to Drupal 8. Instead, you set up a completely new Drupal 8 site, then migrate your existing site to your new one. Given a database connection and a files directory, this auto-generated migration can attempt to replicate your entire site. This is great, but it also replicates all your previous design decisions, mistakes, and cruft.

Instead, you may want to see moving to Drupal 8 as an opportunity to revisit previous decisions and reorganize your content. In that case, you’ll want to create a custom migration. Over the last few months I’ve had the fortune to work on a custom migration for a client. I then decided to apply that knowledge again to my own site.

Preparing your new site

Again, we’re not upgrading, but rather building a new site and then selecting what content and configurations we want to migrate from the old site. As such, the first step is to set up a new Drupal 8 site.

There are many, many good tutorials you can find elsewhere online about setting up a new Drupal 8 site. The tl;dr; version is this: Download Drupal core from, install it, and perform a small amount of initial configuration. You should stop short of adding users, creating roles, or downloading contrib modules.

Step into the web confessional, my child

Confession is said to be good for the soul, and now’s the best time to repent your site’s sins. Do you have content owned by user 1? Are you administrator permissions given out too widely? Did you build the site around any core feature or concept that just never quite worked?

Now’s the time to revisit all of that.

For my site, this process turned into an introspective experience. I’ve had the site since 1999, and have had it on Drupal since 2005. Over the years, I’ve attempted to build the site around some sort of enforced, top-down philosophy. None of that really worked. When I started to redesign the site this time, I decided to take the opposite approach. Instead of formulating some gimmick, I decided to take the opposite tactic.

Perform a Content Inventory

It sounds really dull, but performing a content inventory is an essential first step. Go visit your site and see what you actually do with it. The difficult part is to try to look at it with fresh eyes. You may need to do this on a weekend, while on vacation, or even at 3 in the morning; anything to remove yourself from your preconceptions.

Typically, a content inventory results in a large spreadsheet of content types, titles, owners, post dates, and so on. While books like Content Strategy for Mobile highly recommend this approach, I often find it less than useful. Instead, I suggest you use the inventory as an opportunity to curate some representative content. This is content you think best exemplifies your site. For most sites, this is going to be somewhere between 20 to 200 posts.

The act of curating your representative content should already give you ideas as to what your site is really about and how it should be organized. If you’re still at a loss, perform a card sort.

You can find guides on how to do this around the internet, or you pick up the excellent book, Card Sorting. The card sort is intended to build up a list of types and categorizations of your content. The process isn’t scientific, so feel free to call in friends, family, or coworkers if empathy isn’t one of your best skills.

Survey your users

Now that you have some kind of idea about what your site is used for, next is the really painful part: You need to survey your users.

This part is often really difficult, as you will hear some unpleasant and sometimes, surprising things. Start with the site owner. They will have the most investment and the most ideas. This is both a benefit and a curse as they can carry considerable preconceptions about what the site is for and how it should work. The biggest concern is that they may shout out or unintentionally intimidate others from providing honest opinions. For small business and personal sites, you may not have anyone to really talk to but the mirror. Again, do your best to try to approach it like someone that’s never seen the site before.

If you can afford the time and effort, try to also survey your site’s visitors. Only a fraction of those that visit your site will respond, but the few that do can often provide invaluable insight. If that’s not available to you, ask friends or family to play-act being site visitor and record their observations.

Gather your results

I didn’t follow as formal a process as this with my own site, but I did discover a few important things:

  • Most of my content is in blog posts with limited graphics.
  • No one was happy with the experience of writing on the site.
  • We had several hundred “picture” nodes, but it was badly disorganized.
  • There were 10 “audio” nodes, but they were all podcast episodes for the same show.
  • I really wanted to centralize all my content, writing, photos, art, etc., that was formerly spread across multiple platforms and social networks.
  • Any organization method more complicated than tags was either too complex or too slow.

The picture nodes in particular required a bit of examination to figure out. There were some that were merely used as attachments to existing blog posts. Others were photos from travel or around town. The remainder were pieces of artwork, sketches, or design prototypes.

Imagine and play-test

At this point, we haven’t really written any migrations yet, but we’ve made a lot of headway in figuring out what we should build. Take your representative content and your user survey and use them to imagine your future site.

Ask yourself and your team questions like the following:

  • What do users want when they arrive on your site?
  • What does the workflow look like for each of your content types?
  • Where do users land on your site?
  • If a user wants to read more on your site, how do they find it?
  • Is featuring particular content important to you?
  • Do users leave comments?
  • Are comments even important to you?
  • Do users need to register?

There are lots of techniques to accomplish this such as User Stories. I prefer simple role-playing to put me in the appropriate headspace. Eventually, you’ll have some concept of how your site should be organized, what the workflows look like, and some idea on how to answer the remainder of your questions.

For my site, I came up with the following:

  • In addition to tags, a new taxonomy of “topics” is used to categorize content so that posts related to the same project or idea could be easily found.
  • Travel photos would be migrated to a new Picture Gallery content type.
  • Artwork and creative posts would be added to a versatile Creation type.
  • Paragraphs would be used throughout to simplify embedding and improve the writing experience.
  • Audio posts would be renamed to Podcasts, with an additional taxonomy to allow for multiple shows.


So far we haven’t done much technically to create a custom migration. You may be disappointed, but as a fellow techie I cannot stress enough how important all these preparation, introspection, and play-acting is before you write a single line of code. Doing a content inventory, a card sort, a user survey, all sound like touchy-feely stuff, but it builds a conceptual foundation for the success and effectiveness of your future site.

Read part 2!

Thanks to my sponsors!

This post was created with the support of my wonderful supporters on Patreon:

  • Alina Mackenzie​
  • Chris Weber

Thank you!!!