The ultimate Drupal to WordPress migration checklist

Migrating websites to a different content management system platform is incredibly complex but developers and site owners often underestimate the amount of work involved. Drupal to WordPress migrations can be especially tricky because they target very different types of users. You can quickly run into trouble if you start a migration project without considering some key areas.

My own migration project framework starts off with an analysis phase designed to discover as much as possible about the client’s needs and the impact on project resources. Over the years I’ve compiled a set of questions and considerations specifically for Drupal to WordPress migrations.

Developers and site owners can use this list to better understand their project’s scope. I’ve rather cheekily referred to it as The ultimate Drupal to WordPress migration checklist but in reality, it’s more of a working document that’s continually refined. The checklist is currently organised into three main areas that often concern my clients: understanding their migration requirements, auditing the existing Drupal site and addressing any SEO impact of the migration.

Migration requirements

These migration requirements will help you estimate a budget for your project.

  • List the Drupal content types to export as WordPress pages
  • List the Drupal content types to export as WordPress posts
  • List the Drupal content types to export as WordPress custom content types
  • Will custom content type development be needed?
  • List the content types that will be merged (if any)
  • Do you plan to re-organize your categories and tags?
  • List of terms to export as WordPress categories (remaining will be exported as tags)
  • Do you want to migrate comments?
  • Do you want to migrate Drupal users?
  • What will be your WordPress default category?
  • How do you want to handle the Drupal legacy file directory?
  • Are there any content sources outside of the Drupal database? (For example, static HTML files or external databases.)
  • What will be your WordPress permalink structure?
  • How do you plan to handle URL redirects?
  • Do you expect any data cleaning to be necessary?
  • Do you want me to install and configure WordPress on your server?
  • Do you want me to import the migrated database to your live server?
  • If any problems occur with your hosting provider during the migration, do you need me to troubleshoot?
  • Will you be redesigning your site or do you plan to convert your existing Drupal theme to WordPress?
  • If you plan to redesign your site, will you be using a ready-made theme or custom theme?
  • Who will be responsible for developing and configuring your WordPress theme?
  • Do you need to merge multiple domains or sub-domains into a single WordPress installation?
  • Do you need to merge content and configuration from an existing WordPress installation? (This may be necessary if you have already started developing the WordPress site prior to content migration.)
  • Is there an e-commerce component to the migration?
  • What are your SEO requirements? (We may need to complete the separate SEO To Do list.)

Drupal content audit

Understanding as much as possible about your Drupal installation will help you come up with a more precise estimate for your migration project. The content audit may take some time to complete but the process will give you a better idea of how much work will be needed to migrate your site.

  • Have you created a site map of your Drupal site?
  • What is the approximate number of Drupal nodes to migrate into WordPress. The number of Drupal nodes does not usually play a big factor in the complexity of the migration. However, it will still be useful to get an idea of the number since many nodes can have an impact on how long it takes to troubleshoot migration problems.
  • Please list the Drupal content types to migrate into WordPress. Additional migration MySQL queries will be needed for each Drupal custom content type. WordPress supports page and post content types as standard. Additional development work will be needed to support other content types.
  • Please list your Drupal custom fields. As with custom content types, custom fields in your Drupal installation will need additional work to support them under WordPress. We will need to specify how the field content is stored in WordPress, for example, by setting post meta key strings or custom tables.
  • Please list your Drupal modules and site functionality. Can the functionality can be handled with existing WordPress plugins? Will you need to develop custom plugins?
    Do you have blocks, views and panes with important content? Many Drupal sites display content in this way. Your SEO may be affected if you receive lots of traffic to pages with blocks, views and panes.
  • Have you installed Drupal modules that generate metatag information contributing to your SEO?
  • Do you have on-page optimization coded within the Drupal theme templates that we need to preserve? This will be important for SEO. Usually, on-page optimization embedded into the content body will be preserved during a migration.
  • Please briefly describe what to do with multiple aliases. Drupal supports multiple URL aliases for nodes. These will need to be resolved when migrating to WordPress. How we approach this will have an impact on your SEO.
  • Are there URL structures in Drupal that you need to preserve for SEO?
  • Are any Drupal taxonomies particularly important? Some sites have taxonomy listings that attract valuable traffic so this may be important for SEO. Note that unlike Drupal which allows for multiple vocabularies, WordPress only offers one set of categories and tags out of the box. Replicating your Drupal taxonomy listings in WordPress may need additional development.
  • Please briefly describe what to do with duplicate terms. Duplicate Drupal terms can cause problems during a migration.
  • Please briefly describe what to do with problem terms. For example, WordPress has a 200 character limit for terms. Any Drupal terms longer than 200 characters will need to be truncated. This may impact SEO if you receive lots of traffic from term indexes.
  • How many users do you have? The number of users doesn’t play a big factor during a migration but it may be useful to know. On some sites, users have associated pages that may be important for SEO.
  • Please list and brief description of user roles. Your Drupal user roles may need to be converted into WordPress roles.

SEO

These are tasks for projects where SEO is a major consideration. If SEO is critical to your site, you should hire your own dedicated SEO consultant.

  • Perform a pre-migration SEO audit
  • How will changes to menu navigation affect SEO?
  • How will changes to breadcrumb navigation affect SEO?
  • How will changes to site hierarchy affect SEO?
  • Crawl Drupal site to build database of URLs
  • Crawl WordPress site and compare counts with results from Drupal
  • Build database of authoritative content URLs and ensure these remain accessible after migration (e.g. via redirect if necessary)
  • Ensure changes to WordPress theme template will not adversely affect authoritative content
  • Identify how dynamically generated and statically set URLs will change (for example Drupal node IDs vs WordPress post IDs; Drupal URL aliases vs WordPress permalinks/post names)
  • Build list of changed URLs for redirection
  • Review title and meta description tags
  • Migrate title and meta description tags to SEO plugin e.g. Yoast
  • Identify top keywords and how they will be implemented in WordPress (e.g. do we manually set Yoast focus keyword for posts?)
  • Add Open Graph social meta data (for example via Yoast plugin)
  • Ensure theme is responsive for ‘mobile-friendliness’
  • Install redirection plugin (or implement via htaccess)
  • Install XML sitemap WordPress plugin
  • Install schema markup (rich snippet) WordPress plugin
  • Review WordPress robots.txt file
  • Check legacy Drupal site links to ensure WordPress redirects work correctly
  • Assess how page speed will affect SEO (anecdotal evidence says that page speed improves after a move to WordPress but verification is necessary)
  • Ensure live WordPress site is not set to noindex
  • Ensure correct timezone is set in WordPress
  • Perform a post-migration SEO audit

How to fix ‘Error Code: 2013 Lost connection to MySQL server during query’

Content migrations usually involve running complex MySQL queries that take a long time to complete. I’ve found the WordPress wp_postmeta table especially troublesome because a site with tens of thousands of posts can easily have several hundred thousand postmeta entries.

If your query ends up taking more than a few minutes to complete, you may encounter the following error:

Error Code: 2013. Lost connection to MySQL server during query

This happens because the connection between your MySQL client and database server times out. Essentially, it took too long for the query to return data so the connection gets dropped. The MySQL documentation suggests increasing the net_read_timeout or connect_timeout values on the server. If this doesn’t solve the problem, you may need to increase your MySQL client’s timeout values.

MySQL Workbench

You can edit the SQL Editor preferences in MySQL Workbench:

  1. In the application menu, select Edit > Preferences > SQL Editor.
  2. Look for the MySQL Session section and increase the DBMS connection read time out value.
  3. Save the settings, quite MySQL Workbench and reopen the connection.

Navicat

How to edit Navicat preferences:

  1. Control-click on a connection item and select Connection Properties > Edit Connection.
  2. Select the Advanced tab and increase the Socket Timeout value.

Command line

On the command line, use the connect_timeout variable.

Python script

If you’re running a query from a Python script, use the connection argument:
con.query('SET GLOBAL connect_timeout=6000')

Drupal to WordPress migration consulting

Any Drupal version · All content · Custom content types · SEO · Plugins

Migrating a site from Drupal to WordPress and need a specialist? Please contact me for a quotation. Whether you’re a media agency who needs a database expert or a site owner looking for advice, I’ll save you time and ensure accurate content exports.

Get a quote

Post-migration troubleshooting: Gateway timeout when enabling plugins

Here’s one that caught me out on a recent Drupal to WordPress migration. As is common with my projects, there were three parties involved: the client, an external development team and myself. The WordPress site was first built on the development team’s server, after which it was migrated to my local environment. When everything was ready for beta testing, we moved the site over to the client’s staging server on a newly activated account over at Kinsta. Eventually, we’d move it over to a live server, also hosted on Kinsta.

Diagram of Drupal to WordPress migration workflow for this project

After some initial tests on staging, I found that deactivating and reactivating plugins would cause the site to hang and show a ‘504 Gateway Time-out’ error. This happened when re-enabling some but not all plugins.

I initially suspected some misconfiguration at the hosting end because there were some hitches with the newly create account. At the outset, the account’s server had an issue which Kinsta support needed to fix. For convenience, we’d also made use of Kinsta’s free site migration service. This is where they’ll migrate an existing WordPress site into their environment. Though it would have been easy enough for me to do, we thought to give it a try. In hindsight, this was a bit of a mistake. The site migration service itself was fine but it did end up causing some confusion. First, a miscommunication in the migration request caused them to create a temporary domain we didn’t want. They helpfully solved this by giving us a second temporary domain. However, they’d also upgraded everything to PHP 7 in the process. All of these issues were possible suspects for the time-out error but turned out to be red-herrings.

It took some time to pinpoint the cause behind the Gateway Time-out error. I do have to say that Kinsta support were very responsive throughout the troubleshooting process. They eventually put a senior engineer on the case who found the problem. It turned out the problem wasn’t to do with Kinsta at all. There was a leftover setting from the original development team’s server server. It was a valid format so didn’t cause an issue on either my local server or my staging server. However, it apparently can cause issues with plugins and did on the Kinsta environment.

What was the setting? The WordPress upload path directory was set to the development team’s server path e.g. /home/dev/public_html/sitename. Throughout the migration, I’d been doing a database search-and-replace looking for their development domain. Somehow, as the site moved from different servers, that server path string remained in the database, only to cause a problem when the site landed in the destination server on Kinsta.

I’m not sure if there would have been any way to have caught this problem earlier. It’s one of those obscure errors that are easy to overlook and take time to resolve. There’s also no practical way to do a database search-and-replace for every imaginable string. I’ll have to rack this one up to experience.

How to change the WordPress table prefix prior to a migration

When working on a Drupal to WordPress migration project, I like to migrate into a set of intermediary WordPress tables that live in the Drupal database. These are working tables where I can run various scripts to process and clean up the content before exporting to a working WordPress installation. It’s not necessary to do this but I find it convenient to run scripts on the same database rather than deal with two separate database connections.

Note that some people suggest renaming the table prefixes to improve security. My use of the table prefixes is simply to create temporary containers for the migration. While non-standard prefixes might help prevent ‘script kiddie’ attacks, I find it isn’t worth the disadvantages that come with this sort of security through obscurity (or more precisely, security through minority) approach. Here are two articles give a deeper explanation of topic:

SQL queries to change the WordPress table prefixes

You can start with a freshly installed WordPress database. Dumping this and importing to your Drupal migration database will give you all the tables with the correct WordPress schema. I use the acc_ prefix but you can use whatever you want.

Rename the tables with these queries:

RENAME table `wp_commentmeta` TO `acc_commentmeta`;
RENAME table `wp_comments` TO `acc_comments`;
RENAME table `wp_links` TO `acc_links`;
RENAME table `wp_options` TO `acc_options`;
RENAME table `wp_postmeta` TO `acc_postmeta`;
RENAME table `wp_posts` TO `acc_posts`;
RENAME table `wp_terms` TO `acc_terms`;
RENAME table `wp_termmeta` TO `acc_termmeta`;
RENAME table `wp_term_relationships` TO `acc_term_relationships`;
RENAME table `wp_term_taxonomy` TO `acc_term_taxonomy`;
RENAME table `wp_usermeta` TO `acc_usermeta`;
RENAME table `wp_users` TO `acc_users`;

Testing the migration results

If you need to point a WordPress installation to these tables for testing, you’ll need to do two things:

  1. Update the $table_prefix setting in the wp-options.php file
  2. Update the options and usermeta tables

Updating the $table_prefix setting in the wp-options.php file is straightforward. Open the file and edit the line:

$table_prefix  = 'acc_';

In WordPress, prefixes are saved as entries in the options and usermeta table. Check for entries containing the prefix:

SELECT * FROM `acc_options` WHERE `option_name` LIKE '%wp_%';
SELECT * FROM `acc_usermeta` WHERE `meta_key` LIKE '%wp_%';

When you have all the entries, update them with the new prefix. The query will probably look something like this:

UPDATE `acc_options` SET `option_name` = 'acc_user_roles' WHERE `option_name` = 'wp_user_roles';
UPDATE `acc_usermeta` SET `meta_key` = 'acc_capabilities' WHERE `meta_key` = 'wp_capabilities';
UPDATE `acc_usermeta` SET `meta_key` = 'acc_user_level' WHERE `meta_key` = 'wp_user_level';
UPDATE `acc_usermeta` SET `meta_key` = 'acc_user-settings-time' WHERE `meta_key` = 'wp_user-settings-time';
UPDATE `acc_usermeta` SET `meta_key` = 'acc_user-settings' WHERE `meta_key` = 'wp_user-settings';
UPDATE `acc_usermeta` SET `meta_key` = 'acc_dashboard_quick_press_last_post_id' WHERE `meta_key` = 'wp_dashboard_quick_press_last_post_id';

A word of warning: it’s easy to forget to change the prefixes back to match the final WordPress installation. If you do, the WordPress user accounts will have problems, such as the Dashboard controls not being visible after logging in. Because of this, I tend to have a separate testing installation that gets an import of the working tables.

Post-migration troubleshooting: WordPress redirects to old site after updating database

If you’ve ever migrated a WordPress site, either to another URL or for a Drupal to WordPress migration project, you’ll know that WordPress stores the domain name in its database. This means you’ll have to jump through some hoops when moving WordPress to another environment. A critical step is to update the database to reflect the new domain. My favourite tool for this used to be the database search and replace script from interconnect/it. The script is PHP-based so runs on all environments that host WordPress. I now prefer WP-CLI’s wp search-replace command when on my own development environment, or for client hosting that supports it. Nevertheless, interconnect/it’s tool is still my fall-back option for clients of my Drupal to WordPress migration service since many use hosts that don’t offer command-line access.

In nearly all cases, updating the siteurl and home fields in the wp_options database table achieves the bare minimum to get the site working after migration. Running a search-and-replace across the WordPress database (in particular, the wp_posts table) will resolve broken links containing absolute URLs.

wp-admin still redirects to the old site after updating wp_options?

Once-in-a-while, I’ll encounter a migration project where wp-admin still redirects to the old site even after running through the obvious steps of:

  1. updating the database;
  2. clearing the browser cache;
  3. clearing the server cache.

It happens very rarely so I have yet to discover the cause. I suspect it’s something to do with sites that had a caching plugin installed, such as W3 Total Cache.

If you ever find yourself in this situation, the best workaround is to add the following two constants in wp-config.php:

define('WP_HOME', 'http://' . $_SERVER['SERVER_NAME']);
define('WP_SITEURL', WP_HOME . '/');

This isn’t a nice long-term solution but it should at least enable you to log in for some basic site administration. Once you’re able to log in to the WordPress Dashboard, disable any caching plugins after first clearing their cache.

Handling the Drupal file directory when migrating to WordPress

Attaching media the WordPress Media Library are one of those things that many clients don’t realise can add lots of time to a Drupal to WordPress migration project. The reason is a little detailed and involves some knowledge of WordPress’ inner-workings.

When you upload a file to the WordPress Media Library, WordPress does some magic behind the scenes and creates different bits of metadata. If you upload, say, an image, it creates thumbnail versions of the image based on the settings in Settings > Media Settings > Image sizes. It also adds a bunch of serialized data in WordPress’ attachment table (wp_attachment_metadata). If you get this information wrong, displaying attachments will fail. For example, Featured Images in posts will not display because the theme has no reference for which thumbnail to display when a post is delivered.

Folders symbolising media migration from Drupal to WordPress

Because of the necessary metadata that needs to be generated, attaching media to the Media Library is therefore not feasible through a database migration using purely SQL queries. If you’d like media attached, a separate custom script is needed to pick up all your files under the Drupal file directory and attach them using different mechanisms, such as XML-RPC, WP-CLI or a custom plugin. It adds to the cost so many of my clients see this as a ‘nice-to-have’ rather than a necessity.

As an alternative, my clients and I have come up with different ways to handle the Drupal files and media items when migrating to WordPress:

  1. Leave the Drupal file directory path intact on the WordPress installation server. This is the easiest option which most clients take because it’s cheaper. No changes are needed to the post and page content because the already embedded path will still be valid. However, we may have to make changes to the WordPress theme so that it knows the path to legacy Drupal file path. Future uploaded files will be fine but legacy posts will point to the Drupal file paths. This is not nice and a bit of a hack but it’s a cheap and quick solution. Media items will not appear in the WordPress Media Library.
  2. Move the Drupal file tree to the WordPress wp-content directory. We then need to do a search-and-replace to amend the link path within the post content. There’s a small risk of broken links if we don’t get the search pattern right but generally it’s a straightforward process. Media items will not appear in the WordPress Media Library.
  3. Use a plugin or custom WordPress code to attach files from an external URL. The client’s developer normally handles this work in-house so I can’t offer much feedback on this method. It seems to work reasonably well.
  4. Manually upload all the files to the WordPress Media Library. This is of course the most tedious and time-consuming option. Nevertheless, those with smaller sites or have gone this route. If you’re trying to save on budget and have lots of time on your hands, you might want to consider it.
Graphic courtesy of and copyright morguefile.com user Ladyheart

How to write a Drupal to WordPress migration mapping document

Performing a Drupal to WordPress migration can be very complex, especially if you have many content types. You’ll make the process easier if you create a migration mapping document beforehand. A common migration mapping is to convert Drupal pages to the WordPress page type and Drupal stories to the WordPress post type. However, many Drupal sites also have custom content types so the mapping won’t always be obvious. Will they be converted to WordPress pages or posts? Do they have custom fields? How about views and panels? Perhaps you may need to develop a new WordPress content type to support them.

Your Drupal to WordPress migration mapping document will give everyone involved a clear idea about how the Drupal content will be migrated to its equivalent in WordPress. If you’re running the migration yourself on a simple blog or company site, there might not be much need to spend the extra effort but sometimes running through the process uncovers aspects of the site that you may have overlooked. I’d say this is vital for migrations where you’ve hired someone else or if you have a content-heavy or news-based site. Not only will the document make it easier for someone to quote for the job, you’ll also have a specification for reference when checking the results post-migration.

Creating the content mapping

Creating the mapping needn’t be complex. The easiest way is draw up a table with at least two columns. On the left column, list down all your Drupal content types. Next write down equivalent WordPress content type on the right column for each row of Drupal content types. You might find it helpful to have a third column for writing notes, such as whether or not you need do develop a new custom WordPress content type. If your Drupal content type has custom fields, simply add rows below each type listing the fields.

Sample content mapping table
Drupal WordPress Notes
Drupal WordPress Notes
Drupal WordPress Notes
  Field 1   Field 1 Notes
  Field 2   Field 2 Notes
  Field 3   Field 3 Notes
Drupal WordPress Notes
Drupal WordPress Notes
Drupal WordPress Notes

Developers responsible for the migration can also add additional sections specifying back-end table and field names where the relevant content can be found.

Creating the functionality mapping

Follow a similar procedure to create the functionality mapping. Instead of content type names, list down Drupal modules and equivalent WordPress plugins.

Preparing for your migration project

The migration mapping document will have helped prepare you for your project and provide you with a specification for the migration. You might also find the following articles useful:

A little plug to keep the lights running. If you think all of this work is too much trouble, please consider hiring me for your Drupal to WordPress migration project.

Drupal to WordPress migration service

Drupal 6 and Drupal 7 · All content · Custom content types · SEO · Plugins

If you’re not sure how to make the appropriate changes or would simply like someone else to do the work, please contact me and ask about my Drupal to WordPress migration service.

Get a quote

Importing a WordPress database: How to fix the Unknown collation: ‘utf8mb4_unicode_ci’ error

If you do a lot of exporting and importing to different database servers, you’ll be familiar with the frustration of encountering MySQL import errors. Every so often when importing a WordPress dump file into a client’s database, I will encounter an Unknown collation error like the following:

Unknown collation: 'utf8mb4_unicode_ci'

Sometimes it will come up as:

Unknown collation: 'utf8mb4_unicode_520_ci'

This is caused by a difference in encoding types between the source and destination databases. It usually happens when you export from a newer MySQL database (MySQL 5.5.3 and above) which uses utf8mb4, then attempt to import into an older version using utf8. If you are importing from a dump file generated from a MySQL 5.6 database, you may get the utf8mb4_unicode_520_ci message. The 520 refers to MySQL’s use of Unicode Collation Algorithm 5.2.0. Unknown collation errors may also happen if you are trying to import a MariaDB database into MySQL. I tend to get unknown collation errors with my Rackspace Cloud accounts after Rackspace started offering MariaDB as a database option.

Ideally one would upgrade the older destination database but this isn’t always a realistic option. There are a number of discussion threads on the WordPress forum about what to do. Fortunately, many web hosting accounts have a phpMyAdmin interface which provides an easy work-around for the problem.

Format-specific options during a phpMyAdmin database export

  1. Log in to your database server using phpMyAdmin
  2. Make sure you select your database and go to the “Export” tab
  3. Select the “Custom” radio button
  4. Go the section “Format-specific options” and in the setting for “Database system or older MySQL server to maximize output compatibility with:” select MYSQL40.
  5. Scroll to the bottom and click GO.

phpMyAdmin format specific options to fix the Unknown collation: 'utf8mb4_unicode_ci' error

Other possible solutions include:

Since many of my WordPress database migrations are under my migration service, I don’t always have control over the client’s platform. The phpMyAdmin export format method is often the simplest solution.

Side-effects of a character encoding downgrade

You might be wondering about the purpose of encoding types and if there will be any side-effects of downgrading. Character encoding allows support for a set of characters, such as the Western alphabet, Asian scripts and non-alphanumeric symbols. Older utf8 databases support a smaller set of characters whereas utf8mb4 includes emojis, musical notation and Chinese Han characters. If you’ve ever exported a website from one CMS to another and found random characters scattered throughout the copy, it’s because of an incompatible character encoding.

Solving the unknown collation error as described here could mean you’ll end up with unsupported characters after your site migration. However, as with many of my Drupal to WordPress migration clients, in all likelihood you’ll be migrating from an older utf8 Drupal database to a newer utf8mb4-supported WordPress database. In this case, your old content will not have characters that will cause a problem after an encoding downgrade.

How to prepare for your Drupal to WordPress migration project

Any successful project requires careful planning and a Drupal to WordPress migration is no exception. It can be tempting to head straight to setting up WordPress, trying out new themes and experimenting with plugins. Website owners and administrators know their content is important but it can sometimes become an afterthought in the excitement to play with the new content management system. After all, you can use the Drupal site as the template and simply export over all the content over, right? For some site owners that’s all there is to it. However, you should be aware that site migrations can have hidden pitfalls that turn an apparently simple project into one fraught with complications.

The key to avoiding problems is to plan your Drupal to WordPress migration before you even touch your server. Whether you migrate the site yourself or hire me to help you, this guide will give you a head start with your planning. Keep in mind that general project planning principles apply but there are already many resources on this topic. I will focus on the areas important specifically for a migration from Drupal to WordPress.

Drupal to WordPress migration planning

Step 1: Consider why you are migrating to WordPress

There are many content management systems available and I’m going to assume you have already thought carefully about why you’ve chosen WordPress. For the sake of completeness, I’ll include this step because your reasons will determine whether or not the migration project will be a success.

In case you need a reminder about the merits of either CMS, here are a few Drupal vs WordPress posts:

If you haven’t already put together a migration requirements document, go ahead and create one now. I go through this migration requirements checklist with my own clients and it might help you too.

Step 2: Decide on your approach to building the WordPress theme

The WordPress theme, just like in Drupal, is what handles how your site looks. A migration to a new CMS often goes hand-in-hand with redesigning the site. I’ve put this step early on because a site redesign could be an entirely separate project. You might want to run in parallel with the migration or it could be something you’d want to start before kicking off the content migration.

You have three options:

  1. Redesign the WordPress site entirely.
  2. Create a custom theme based on your existing Drupal design.
  3. Use one of the many pre-made free or premium WordPress themes.

If you have a successful site, any change, whether it’s a redesign, restructure or move to another content management system should be carefully considered. This article at Search Engine Journal gives an excellent overview of the things you should keep in mind: How To Avoid SEO Disaster During a Website Redesign – Top Marketer Concerns

Step 3: Be aware of any SEO impact when migrating to WordPress

WordPress has an excellent reputation for being SEO-friendly but beware of taking this for granted. The Search Engine Journal post linked in step two should have given you a sobering outlook on how making changes to your site will affect your SEO. In my experience, preserving SEO takes a large part of the time and budget of many migration projects. Sometimes the cost will outweigh any benefit of trying to preserve the SEO customisations on your Drupal installation. This is often a commercial rather than technical decision. If you run a site that relies on search traffic, I recommend that you hire an SEO consultant to advise you. In fact, I will often work with and take direction from a client’s SEO consultant during a typical Drupal to WordPress migration project.

For more information about the kind of work involved, see Preserving SEO during a Drupal to WordPress migration. This SEO checklist will help get you thinking about any SEO impact the migration will have to your site.

Step 4: Gather as much information as you can about your Drupal installation

Knowing as much as possible about your Drupal installation will help me come up with a more precise estimate for your migration project. If you’re doing the migration in-house, it will help you plan how much time to set aside and which team-members need to be involved.

Site owners who built and manage the site will likely have records of some information but not necessarily all the details of how Drupal is configured. Site owners also come to me with a site built by a third-party. They have working knowledge on how to manage it and add content but not anything else. I can help you discover the information needed for the migration if you are in this position but you can save budget by doing some investigation yourself. Use my Drupal to WordPress migration worksheet as a guide.

The formal name for this is a site audit but essentially you need to find out about two areas:

  1. How to access your server
  2. What kind of content you have

Server audit

You’ll need your FTP server details to access your Drupal installation, media files and to upload the WordPress package. When running a migration, I like to download a full working version of the Drupal site on my local development server. This isn’t necessary but can be useful for figuring out formatting problems that crop after content migration. For example, you may find missing bits of text on WordPress and some investigation on the Drupal installation will show the text will be from a custom field or block.

The database server is necessary for exporting your Drupal database and setting up WordPress when the migration is complete. Some hosting providers offer access through a cPanel interface, a separate phpMyAdmin link or by command line. Gather all these details ahead of time will help get your project started quickly.

Content audit

The content audit helps you discover what type of Drupal content do you have. Drupal, like most other content management systems, keeps content in two places:

  • The database
  • On the server filesystem

Types of content include:

  • Nodes
  • Views
  • Blocks
  • Panes
  • Taxonomies
  • Static HTML files
  • Embedded media like videos, images and audio
  • File attachments
  • User profile information
  • Content metadata

You may be surprised where the different bits of content that make up your site ends up being stored. A content audit will avoid unnecessary complications with trying to hunt down bits of data mid-migration. My Drupal content audit checklist should get you started.

Step 5: Write a Drupal to WordPress migration mapping document

The migration mapping document will help both with quoting for project as well as keeping track of everything that needs to be done during the migration. It gives everyone involved a framework to work on.

I know, this sounds like a mouthful and so very tedious. Truth be told, few people find writing specification documents fun but it is a necessary step if you want to avoid unexpected costs and delays. The more detailed you are, the fewer surprises there will be for everyone during the actual migration. Your investigations during step 4 will lay the groundwork for the migration specification.

I will write another post on how to write migration mapping document but the document doesn’t have to very formal. All it needs to do is clearly convey the state of your Drupal site and what you’d like migrated to WordPress.

Ready for your migration project

Running through these steps will put you in a good position for your migration from Drupal to WordPress. Admittedly, there have been projects where I or the site owner didn’t bother to do any detailed planning and we were able to get by. Usually, this was because of limited budget or a rush to launch the new WordPress site. However, the projects where we took some time out to plan ahead were always closer to the estimated budget and posed fewer surprises.

A little plug to keep the lights running. If you think all of this work is too much trouble, please consider hiring me for your Drupal to WordPress migration project.

Drupal to WordPress migration service

Drupal 6 and Drupal 7 · All content · Custom content types · SEO · Plugins

If you’re not sure how to make the appropriate changes or would simply like someone else to do the work, please contact me and ask about my Drupal to WordPress migration service.

Get a quote

Planning graphic courtesy of and copyright Free Range Stock, artist: Jack Moreh

Drupal to WordPress migration worksheet

If you are using my Drupal to WordPress Migration Tool or have hired me for Drupal to WordPress migration service, it’s important that you gather as much information as you can about your Drupal installation. The more detailed you are in your investigation, the fewer surprises there will be during the actual migration. You may have hired a web development company or freelancer to build your site and they’ll sometimes be able to provide you with the necessary information. However, gathering this information can involve some work so they may be reluctant to provide help without an extra fee.

You can use the questions below to help structure your investigation process. I can help you with this if you’re not able to run the investigation yourself. Please ask for details.

Note: You may print out this worksheet as a guide so you can record your investigations. It is not an online form. I will send you a link to my online form if you’d like me to quote for your migration project. You may also download a PDF version of my online form.

Drupal Installation Questions

  1. What are the FTP login details of your hosting provider?

    You will need these details to make a backup of your Drupal site. When the migration is complete, you’ll need them to install WordPress on your server.

    FTP Credentials
    Host  
    Port  
    Protocol  
    Username  
    Password Send through secure channel e.g. password manager
  2. What are the database login details of your hosting provider?

    You’ll need these to export your Drupal database to perform the migration.

    Database Credentials
    Host  
    Port  
    Database name  
    Username  
    Password Send through secure channel e.g. password manager
  3. Do you know how to export your database to a dumpfile?

    If you’re unsure how to export your database to a ‘dumpfile’, please contact your hosting provider. They will likely have tools such as phpMyAdmin and help articles to guide you through the process.

      Yes/No
    I know how to export my database to a dump file
    I need help exporting my database to a dump file
  4. What version of Drupal are you running?

    The database column names differ slightly between Drupal versions. This means that a different set MySQL queries will be needed to perform the migration. You can sometimes find this information using your installation’s CHANGELOG file at http://[YOURDOMAIN.COM]/CHANGELOG.txt. Some developers remove this file as part of their security hardening process so it may not exist in your installation.

    Drupal version
  5. List your Drupal modules and site functionality

    Can the functionality can be handled with existing WordPress plugins? Will you need to develop custom plugins?

    Drupal modules and functionality
     
  6. How many custom content types do you have set up?

    Additional migration MySQL queries will be needed for each Drupal custom content type. WordPress supports page and post content types as standard. Additional development work will be needed to support other content types.

    Drupal custom content types
     
  7. How many custom fields do you have set up?

    As with custom content types, custom fields in your Drupal installation will need additional work to support them under WordPress.

    Drupal custom fields
     
  8. Do you have blocks, views and panes with important content?

    Many Drupal sites display content in blocks, views and panes. These will also need additional work to support under WordPress.

    Drupal blocks, views and panes
     
  9. How many nodes do you have?

    The number of Drupal nodes you have does not usually play a big factor in the complexity of the migration. However, it will still be useful to get an idea of the number since many nodes can have an impact on how long it takes to troubleshoot migration problems.

    Approximate number of Drupal nodes
  10. Do you expect to have multiple aliases referencing the same post?

    Drupal supports multiple URL aliases for nodes. These will need to be resolved when migrating to WordPress. For more information, please see my article Preserving SEO during a Drupal to WordPress migration.

    Brief description of what to do with multiple aliases
    It’s OK if you don’t know. We can discuss your options.
     
  11. Do you expect to have duplicate terms?

    Duplicate Drupal terms can cause problems during a migration. For more information, please see my article Handling Drupal terms during a Drupal to WordPress migration

    Brief description of what to do with duplicate terms
    It’s OK if you don’t know. We can discuss your options.
     
  12. Will your terms exceed the WordPress’ 200 character length?

    WordPress has a 200 character limit for terms. Any Drupal terms longer than 200 characters will need to be truncated.

    Brief description of what to do with problem terms
    It’s OK if you don’t know. We can discuss your options.
     
  13. How many users do you have?

    The number of users doesn’t play a big factor during a migration but it may be useful to know.

    Approximate number of users
  14. How many user roles do you have?

    Your Drupal user roles may need to be converted into WordPress roles.

    List and brief description of user roles
    It’s OK if you don’t know. We can discuss your options.
     

WordPress Installation Questions

  1. Will preserving SEO be an important part of the project?

    For more information, please see my article Preserving SEO during a Drupal to WordPress migration.

      Yes/No
    Preserving SEO is important for this project
  2. Aside from migrating to WordPress, do you also plan to redesign the site?

    Redesigning the site will obviously involve more work as it will require a custom WordPress theme. Some site owners are happy to use a free or premium off-the-shelf theme template.

    Ideas for the WordPress theme
    e.g. list the names, URLs and prices of any pre-made template candidates
     
  3. Are there existing WordPress plugins that match your Drupal functionality?

    If you’re happy to be flexible, you may find WordPress plugins that closely match any Drupal modules you have installed on your existing site. Set aside some time to search the WordPress Plugin Directory. If you don’t find anything suitable, you may have to consider setting aside some budget for custom plugin development.

    List some possible WordPress plugins you may have found