Migrations from Drupal 7 can be as varied and diverse as humanity itself. Goals, audiences, servers, content models, and more all come together to form a unique fingerprint. No two migrations are ever really the same.
But despite the uniqueness of each, there are some commonalities. You can take steps to ensure your migration will be a success, no matter how complex or simple.
You just need to start planning it out.
Map out your Source
You need to know where you are coming from. This is how you begin to determine the length of the journey and how many supplies you’ll need along the way.
Start mapping out your current Drupal 7 website.
Fields and content types
Make a list of all of your current fields and the content types they are attached to. Include the field type, machine name, and the complexity of the data stored in that field. You can come up with your own complexity scale that makes sense to your team. Some examples:
- Basic - A single-value textfield
- Intermediate - A formatted textfield. These fields can range in complexity depending upon what is allowed. Some allow only links and basic formatting, which are not complex, but others might allow embedded snippets and images. Move the scale accordingly.
- High - Multi-value fields with multiple columns of data almost always need extra work to migrate. Field Collections and Paragraphs might fall in this category.
- File - Sometimes, categorizing complexity by the type of data can be helpful. It depends on your eventual workflow or how many fields of a certain type you may have.
Spend some extra time thinking about your entity reference fields. More on this later.
For a quick start on getting all of your content types and fields listed in a spreadsheet, check out the Migration Planner module. View a sample spreadsheet created by the module.
Taxonomy
Taxonomy vocabularies can also have fields attached, so you’ll want to make a list similar to what you have done with content types and their fields. But taxonomies have their own challenges.
Often, they help organize a Drupal site. By design, they are referenced by other entities and can have all the migration issues that come with that.
Taxonomy terms can also have their own hierarchy. If you have terms that are parents of other terms, find a way to record this relationship. Make a note of the depth.
Files
Drupal 7 has many ways to manage files, so you need to document exactly what you have. You are likely using the Media and File Entity modules. Document which file types you are using, how many of each file type you have, and get an estimate of the storage space being used. As you did with content types and taxonomies, list the fields for each file type and categorize them.
If you are using native file handling, you will still want to map out what you have. Your developers will thank you.
Views
There is no way to migrate your Views reliably, so each will need to be recreated on your new site. Each one represents some work. Some might rely on extra business logic in custom code or on plugins provided by contrib modules. Do an audit and determine any dependencies.
Architecture
You will start to map out the contours of this as you take stock of your content types, taxonomies, and fields, but other things make up your overall architecture.
- Menus - Not just the main menu and footer menus. Make sure you pull in contextual menus that might be embedded conditionally or placed via a block.
- Other entities - Do you have other content entities besides nodes and taxonomies? Don’t forget about them. These could be custom components or something like Paragraphs.
- Hosting - Detail out your current hosting platform. Resources, apps, integrations, etc. This might be something else you need to upgrade to ensure the smooth running of Drupal 10. Or you might be migrating onto a different hosting provider, and if that is the case, you want to at least keep parity with your current solution.
Pay special attention to your entity reference fields that you identified in previous steps. These can mask hidden domain knowledge and act as pillars for your entire site architecture. Dig into them. Make sure you know their purpose.
Contrib modules
Make a list of all Drupal 7 contrib modules you have installed. Contrib modules can represent a lot of effort in a migration, so you’ll want to explore each one in-depth. Is there a Drupal 10 equivalent? If so, is the new module stable? How much work is left?
Alternatively, a module could have been rolled into Drupal core. If so, you’ll want to see if there are any differences so you can take those into account during the migration.
If no current module exists, what is the estimated level of effort to recreate this functionality?
Custom functionality
Make a list of all of your custom modules. Be sure also to make a note of business logic that might be in your custom themes. A lot can be embedded in template files.
You should note the complexity of the functionality and what it is used for. You’ll want to check the Drupal 10 contrib ecosystem to see if any modules can replace this custom functionality. This might entail conversations with your stakeholders and team about priorities and goals. A contrib module might replace 80% of your custom module, and you need to know if that is acceptable or not.
If you have limited resources, you might also want to mark custom functionality on a spectrum of “mission-critical” to “nice-to-have.”
These conversations will continue as you map out your destination.
What do you not want to migrate?
Now is a good time to do a site audit. As you are compiling all of this information and start having conversations around your goals and content model, come up with criteria for what shouldn’t be migrated. The less you have to migrate, the less work you’ll need to undertake.
Is there a cutoff date for old articles? A certain taxonomy that is no longer used? Are some fields for cosmetic purposes, and they won’t be relevant for your new design? Do all users need to be migrated over? What about unpublished content? Or revisions? Cutting out revisions will reduce the size of your database drastically, but then editors will not be able to view past changes.
This is where a little bit of work can pay big dividends later.
Some additional questions to ask
- How will you handle files? Files can be transferred during the migration itself, but sometimes it’s better to do one big transfer, so your migrations run more quickly. This usually means some cleanup of unused files beforehand. If you have a lot of files not managed by Drupal, moving the filesystem in bulk might be necessary.
- Will you keep the same paths for your content or change them? If your paths are changing, be sure you have a good 301 redirect solution in place.
Map out your Destination
You need to know where you are going. This can be done in parallel to mapping out your source because what you determine here will help answer some of the questions above.
Start by figuring out the literal destination for your new Drupal 10 site: the servers and hosting. Whatever your setup, you’ll need to plan some way for it to access your Drupal 7 site. This can be as simple as copying the database and files over to the new platform.
But if your site is huge, or you want to do a continuous migration until a final cutoff date, you’ll want access to the live production data. Or at least a replica that stays up to date.
You’ll also want to make plans for a development or testing environment that will mimic your final destination server as much as possible.
Evaluate your content model
You can keep everything exactly the way it is. Same content types. Same fields. Same everything. Drupal will do a good job of re-creating these for you on the new site. If you are limited in time and budget or your site is not complex, this might be the best way to go.
Be warned. If you have relied on the body field for creating complex content, you will still have a lot of work to do, even if you don’t plan on reworking your content model. And regardless, you still need to understand the gaps created by your custom functionality and reliance on certain contrib modules.
For these reasons and many others, a migration is a good opportunity to rework your content model to better align with your strategy and the needs of your audiences. Especially editors. Don’t forget them! It’s also a good opportunity to structure your content for the needs of a “publish everywhere” ecosystem.
Run some workshops that clarify your priorities. Document a new content model that takes those priorities into account. Add additional columns to the spreadsheet you created for your source content types and fields. These columns should contain the machine names of your new content types and fields.
Sometimes you’ll find a need to consolidate content types and/or fields. Two content types funnel into one new content type. Or three different fields are cleaned up into one single field. That should be expected. And Drupal’s migration tools make it simple to do this.
Clarifying your new content model will also help answer questions about your Drupal 7 site, like what content you need to leave out of the migration.
WYSIWYG cleanup
Your body fields (and other formatted text fields) might have accumulated a lot of cruft in the years your Drupal 7 site has existed. Different ways of displaying images, iframes, custom embed codes, etc. You’ll have to deal with each of these.
Cleaning up a formatted body field can balloon into an entire project by itself. Be sure you inventory everything that occurs in a body field, document what needs to be migrated as-is, document what needs to be transformed, and document what can be ignored or deleted. If you are changing your text filters and formatting rules, you’ll want to make sure your content meets those new requirements.
The SQueaLer module helps you find these issues, among other things. This is still in development and might need some tweaking to work with your particular Drupal site.
Again, having conversations around your new content model will pay heavy dividends here. You can come out of this migration with not just a new website but a better website that better accomplishes your goals.
And a website that your editors actually like to use.
WYSIWYG cleanup goes a long way. Don’t limit cleanup to code, either. Sometimes, manual cleanup makes more sense.
Development Workflow
Once you have mapped your source and destination, you’ll be able to start estimating the level of effort involved.
Team planning
A lot of migration work can happen in parallel, but the schedule will depend upon your budget and the team you have in place.
We have seen migrations be successful with one backend developer, and we have seen migrations be successful with four back-end developers. There is a point of diminishing returns. You don’t want too many cooks in the kitchen. If you have experienced developers on your team, they should be able to help you determine when you might reach that point.
Splitting up migration work based on field types has worked well. We have found it helpful to start with more basic fields to get momentum. You get the overall processes hashed out without worrying about complex data sets and transformations.
An example way of breaking up responsibilities between developers might look like the following:
- Basic fields and simple formatted fields
- File/image fields
- Paragraphs, field collections, and other entity references
- WYSIWYG cleanup
- Contrib module updates and replacements
- Custom functionality
There will be some overlap and bleeding across these boundaries, but these are a good starting point in terms of spheres of initial responsibility. Keep in mind that the complexity of your content model can have big ramifications for your team planning.
Solution preferences
When configuring a particular migration, you want a clear order of preference for the solutions you use. This will help save you from extra work and unnecessary technical debt.
The simplest migration entails mapping one field to another in a configuration file. Even basic transformations can be accomplished with this. These will usually invoke plugins that are included in Drupal core or contrib modules. Start here first.
If core and contrib fail you, move to writing your own source, process, or destination plugins. This should cover most of your use cases.
For certain edge cases, you can invoke hooks and react to events at different stages of the process.
QA and testing
Migrations require QA and testing, so be sure and budget time for that. Having a good development server or environment builder like Tugboat will allow migrations to be run and issues surfaced.
Stakeholders can check migrated content to make sure everything shows up as expected. Other developers can validate results and look at the underlying data structure.
This is also where you’ll want to grab any logs generated by the process.
Logging and exceptions
In our experience, migrations create a lot of noise. Warnings, errors, notices, etc. Some of these can be safely ignored, but to figure that out, you’ll want to pay attention to the logs. This is more important if you have several developers working in parallel or you are migrating several sites, each of which might have different edge cases.
But even if you have just one backend developer on the task, you’ll want to make a habit of going over the logs regularly.
- Some can be ignored. Ignore them.
- Some need greater clarification from a developer. Make those clarifications and see if a new ticket needs to be created.
- Some need the attention of a stakeholder. Circulate these and discuss them in your status updates. If you aren’t sure how to handle that rogue iframe, ask.
- Some need fixing. Though some might also be a low priority. If so, make a ticket, put it in the backlog, and keep moving.
When logging issues, be sure to record the current row id and the relevant migration id. This practice can help you find edge cases. Core and contrib migration plugins will provide logs, but if you end up writing custom plugins, be sure to add logging with clear messaging wherever issues might happen. Write custom plugins defensively.
Nested fields (Paragraphs and Field Collections)
If you are dealing with nested fields of structured data, pay special attention to how they are structured and how you will deal with them on the new site.
Paragraphs and Field Collections are the most common, but you might also have a custom solution build with entity references and content types. There are a lot of different ways you can go, and each way has its challenges. It also depends on how your editors best like to work.
Paragraphs to Paragraphs? If so, are you changing the structure?
Field Collections to Paragraphs?
Paragraphs or Field Collections to embedded entities in the body field?
Paragraphs or Field Collections to a custom structure implemented via entity references?
Or maybe you have embedded entities and want to migrate them to Paragraphs?
This is why evaluating your content model is so important. Each path has implications. You don’t want to simply choose the default path. You want to choose a path with intention, with your eyes open, understanding the challenges you need to overcome to get to the other side.
Summary
Planning properly can help you budget properly for both team size and timing. You can get a bigger picture and map out the potential minefields before you even start on your journey.
- Map your source
- Map your destination
- Pay attention to WYSIWYG cleanup
- Think about your development workflow to maximize resources
If you want an experienced partner that can help you through every stage of the migration process, reach out. We would love to help.