Drupal 8.3 Migration - Better, But Still Limited

Submitted by Kevin on Tue, 06/27/2017 - 16:17

A little over a year ago, I wrote about the usability of the Migrate tool in Drupal 8.1.  We're now up to Drupal 8.3, and while Migrate has improved a little bit, it's still officially an experimental module, and still has some notable gaps.  This doesn't mean that you can't successfully use it, but you do have to understand what you're getting from it and prepare yourself to bridge those gaps by hand.

The instructions I gave in my previous post are still valid, so I won't waste space repeating them here.  Instead, I want to start by explaining how the Migrate tool works, so that you can better understand its limitations.

How Migrate Works, and Why it Still Doesn't Work in All Cases

Migrate is just a framework tool.  It provides an API for creating "Migration Paths", which define how to migrate some piece of content or configuration from some other system to the current Drupal system.  It's been around as a third-party module for a while, and was adopted into core for Drupal 8.  Paths can be written for just about anything that resembles a CMS, and there have been extensions for Migrate for Drupal 7 to let you import from WordPress and other popular CMS's.

For Drupal 8, the responsibilities of migration have been delegated out to each individual module, including each individual core module.  So, all the maintainers of the Migrate module are responsible for are the API and the GUI for utilizing it.  This means that your ability to migrate something rests solely in the hands of the maintainer(s) of the module that provides that functionality.

This is as it should be - there are far too many modules out in the wild for any one entity to try to be responsible for migration paths for even a fraction of the most popular modules.  For modules that haven't been ported to Drupal 8, the solution is pretty straightforward:  find another module that does the same thing, write your own, or forgo that functionality when you upgrade your site to Drupal 8.

The real challenge is with modules that have been ported to Drupal 8.  You would expect all of them to have migration paths built out, but many do not.  Even some core modules, like Book and Entity Reference do not.  Thus, even today, when you perform a migration, you're going to inevitably see a lot of missing migration path warnings, and will have to do a lot of manual recreation of configurations and content.

The upside is that you have a good opportunity to do things over in better ways.  The downside is that it's going to take longer to migrate a large, complex site than it might have to upgrade the same site from Drupal 6 to 7.

Below are a few notes to help you along the way.

A Clean Site Is an Easily Migrate-able Site

One of the biggest limitations to Migrate is that you can't pick and choose what comes over.  Any defined Migrate path is automatically applied when you run the tool.  This means that every Content Type, Menu, User Account, User Role, Text Format, Taxonomy, Node, Block, and any other element for which there is a path is copied over to your Drupal 8 site.  As there is some standardization in default element IDs between Drupal 7 and 8, you'll find that many default elements will be overwritten in Drupal 8:  'Basic' content type, all of the default menus, 'Administrator' user role, 'Basic HTML' and 'Full HTML' text formats.  This may or may not work well for you depending on how much you customized those elements in Drupal 7, and how well those customizations still work in Drupal 8.

So, the best plan is to clean up your Drupal 7 site first, deleting any development junk that you no longer need.  If you're uncomfortable doing this on your live site, you can always clone your Drupal 7 site and then clean up the clone.

One thing to absolutely clean up are text filters.  I've found that if you have a text filter enabled on Drupal 7 that doesn't exist in Drupal 8, any text format using that filter will not transfer over, and any content / fields using that text format will get set to a 'null' text format, which causes weird results and can require some database manipulation to fix.  The best thing to do is to uninstall all text filters from your Drupal 7 site (or a clone of it), migrate the site, then enable any equivalent filters on the Drupal 8 site.

Key Modules With No Migration Paths

  • Entity Reference - This is heavily utilized by Paragraphs, so neither entity reference fields nor Paragraphs bundles and bundle content will come over to your Drupal 8 site.  I don't know of any good solution for this right now except to recreate these fields and bundles by hand.
  • Book - This one baffles me, as it doesn't seem like it would be that hard for the Book maintainers to write a migration path, but there still is not one in Drupal 8.3.  Your Book nodes will come over just fine, and have done so since Drupal 8.0 - it's just your page organization (the tree structure) that is not automatically migrated.  For a small book, it wouldn't take that long to reorganize the pages by hand.  For a book with dozens or hundreds of pages, you'll want some help.  Fortunately, I was able to write a stand-alone script to do the work, and I'm happy to share that with anyone who might need it.
  • Block Reference - Not a core module, but one utilized by GT Tools special content types (Horizontal Landing Page, Vertical Landing Page, Multipurpose Page).  Block Reference has been deprecated and is unlikely to ever have a Drupal 8 version, so if your site uses these GT Tools based content types, you'll have to recreate any pages using those types in some other manner in Drupal 8.  Paragraphs is a useful alternative to consider.
  • CAS - The CAS module for Drupal 8 has matured a lot, but it still isn't bringing over your Drupal User account to CAS User account mappings.  For a small number of users, you might can get away with adding these back in by hand (you just have to edit each user account and fill in the CAS User Account field).  For more than a dozen or so users, it should be possible to write a PHP script to autofill the external auth database table using the Drupal user account name as each person's CAS User account.  I haven't written such a script yet, but I may end up writing one sooner or later.

Other Migration Notes

  • Heed carefully the warning that anything and everything will be overwritten during the migration process.  Don't create anything on the site or pre-configure anything until after you complete the Migrate process.  All elements are brought over and written out based on their machine IDs, so anything that already exists under that machine ID will be overwritten.  This includes Content Types,  Menus, User Accounts, User Roles, Text Formats, Taxonomies, Nodes, Blocks, etc.  All you should do before running Migrate is to just install (but not configure) any modules that have migration paths you want to utilize.

  • Be very aware that user #1 will be overwritten with the full details of user #1 from your original site.  If you don't know the password of user #1 on the original site (which is possible if you've been using CAS authenticated accounts to manage that site), make certain to reset the password before logging out to save yourself some major headaches.  Also take note of the username of user #1, as that could be different on your original site as well.

  • Take a good look at your "Basic site settings" in the "System" configuration area.  Make sure the system email address still makes sense.  You'll also most likely want to delete anything in the "Default 403 (access denied) page" and "Default 404 (not found) page" fields.  I'm finding that a path of '/' is getting imported into these fields, but that completely breaks the system when a non-existent page is accessed.  Just delete the '/' to make these two fields blank, and everything should start working normally again.

  • Embedded images in content come over just fine, but the CKEditor image widget doesn't know how to deal with them, since it's been redesigned to handle new image uploads itself.  Over time, you may want to update your pages and replace images embedded as attachments (or via IMCE) with copies uploaded directly to the page to take advantage of the simplicity of the new CKEditor image widget.

  • Blocks are a bit annoying, as Migrate tries to bring over all block placements in all active themes, but some aren't likely to work out right in Drupal 8.  If you utilize 'Seven' as your administration theme, plan on cleaning up the block placements for it, as you'll get some weird stuff going on there that you'll only see when you are using the administration pages.