Why?
Drupal 7 is reaching end of life on November 1 2023. Once that date has been reached you’ll have no further safety updates or new features. The current version of Drupal, Drupal 9, is the active version of Drupal where new features are being developed and the version which will have the smoothest upgrade path in the future. It is strongly recommended that all sites on Drupal 7 be upgraded to Drupal 9 so at to remain supported and secure in the future.
Moving from Drupal 7 to Drupal 9 is not a trivial process as it is not a simple matter of just updating the code and calling the job done. Drupal 9 is based on a different architecture to Drupal 7 so the process should be viewed as an upgrade and a migration. The site essentially needs to be rebuilt and then the content can be moved over. It’s like with old versions of the operating system when you’ve had to save your data first, then delete the old system before installing the latest version and moving your data to the new operating system.
The good news is that there are a number of automated tools which can make the migration process easier. Drupal 9 has a suite of “migrate” modules which makes the mapping and import of data a repeatable process, allowing for migrations from the old to the new quite a bit easier. Morpht has also developed a number of best practices around the migration of data to ensure that problems can be identified and remediated in efficient ways.
How?
There are basically two ways of migrating content when you update from Drupal:
Manual and Automatic
When you have a relatively simple website it’s worth moving your content manually instead of developing migration procedures because it’s cheaper, faster and also you may review the content, rewrite it if necessary. This approach is generally only useful for the smallest of sites.
Most of the sites Morpht works on will tend to be large and complex and will require automatic and repeatable processes for the migration. Oftentimes there will also be the need for content remapping and additions or alterations to the content schema to take in to consideration
Sometimes it is not clear which way to go and a decision needs to be taken based on a number of factors. Even if manual content migration may require a little bit less time, it’s worth choosing automated migration because of several factors:
- Manual process is error-prone, editor like any other human makes mistakes that are hard to track.
- Any data transformations that you’ve decided to apply along with migration make errors more likely.
- Automated migration allows you to have as many iterations as you want to add small changes along the way.
In a nutshell, an automated process allows for corrections and improvements to be made along the way. For instance, you’ve migrated the whole content and then found out that some of the content has classes attached to the HTML tags. In automated migration, we can roll back, make changes to the process and migrate back with the classes being stripped out. In the case of manual migration, this would mean many hours of manual labour with no guarantee of fully cleaned tags.
Planning
Any migration starts with a thorough evaluation of the existing content model. This includes the following items:
- Content types
- Taxonomies
- Paragraphs
- Media
- Blocks
- Fields
All this has to be put into the spreadsheet for mapping and analysis. This definition phase is vitally important for the migrating team as well as the client as it gives everyone a chance to review what currently exists and where the migration process is going.
It is also important to review the content itself. Fields may be defined in one way but used in another. Editors may have been entering junk data, not entering data or using fields in ways in which they were not intended. It is important to understand how the site has actually been populated so the migration process can succeed on a practical level.
During the mapping planning we can not only transfer content from old to new but also transform it in any way we want: concatenate fields, split them or move from one bundle to another depending on some condition. There are a lot of build-in plugins in Drupal migrate and migrate plus module and you can always create your own plugin to handle any scenario.
Extract
Data needs to be extracted from the Drupal 7 site before it can be migrated. Obtaining data from Drupal 7 may be accomplished in several ways: Drupal 7 SQL database, JSON, CSV and others. In some cases, it’s worth creating a view to export rows from the legacy website, one of such cases is file migration.
Transform
At this stage of Drupal 7 to Drupal 9 migration, we implement all the processing that has been planned earlier. Concatenation, trimming, conditional bundle select: all this can be done using inbuilt or custom plugins which allows us to do almost anything with data before it is loaded into Drupal 9..
Load
Loading data to the new Drupal 9 website happens straight after its transformation. This process can be easily rolled back so if you need to make any changes to the transform stage, it’s feasible within one click. Usually, this process is being initiated several times to capture the changes necessary after migrated data evaluation.
For example, the site owner may decide to skip the import of articles of a certain type after the migration is finished. In this case, it can be reversed, with necessary changes to be made to the transform stage and then run the migration again.
Reviewing
Once the data has been imported into the Drupal 9 site it can be reviewed by the migrating team and by the client. During our QA process we check for:
- All field data being populated correctly
- Menu and book hierarchies being retained
- URLs and Path aliases being created correctly
- Content being styled correctly
- Media and Files being included correctly.
The client will generally have feedback at this point in the process. If there has been any sort of schema update or remapping, there will need to be a careful review of the data as it has come across. This may actually lead to the client having to make remediations in the source data so that it is able to come across more smoothly.
Remediating
The review process will naturally throw up problems. Migration needs to be viewed as an iterative process. Migrations will generally need to be run a number of times to iron out any kinks which are found.
Common Gotchas
Redirects
Most likely, your content will have different URLs once migration is finished. At the conclusion of the migration process a CSV file of all of the redirects will need to be uploaded to the new site. The redirect mappings can be retrieved from the new site., At Morpht we keep a record of the legacy URL in the new content, so that we can easily produce a CSV of the redirects.
Broken links
As a part of the migration your content should be checked against broken links which may appear either from the content itself or as a result of migration. Detecting broken links helps you modify migration processes so they will no longer appear. At Morpht we have a link checker script which evaluates all images and links on the site and confirms that the internal URLs actually work. If they do not, the error is logged into a CSV file. We are then able to use this log to define extra mappings to “heal” the broken internal links in the site. This approach is very effective in quickly improving the quality and reliability of the content in the site.
Media
Media entities are another tricky thing that needs some attention. The main thing about it is that in Drupal 8 files became entities (compared to regular files in Drupal 7). The concept of the Media library was also introduced where each File has an associated Media object. It is good practice to treat Files as Media so they will need to be upgraded in the migrate process
Markup
Some of the content may have inbuilt markup and classes assigned to it. These legacy classes will not necessarily map to the class being used in the design system on the new site. A decision needs to be made what to do with these classes:
- Strip
- Change
- Keep and ignore
- Keep and implement in CSS.
At Morpht we run an audit on all of the classes used on the site and record frequency counts for each of them to gauge how widely they are being used.
Case study
One of the challenging migration projects that Morpht implemented recently was for a federal government agency which had around 250 000 nodes and 50 content types. During his Drupal 7 to Drupal 9 migration we followed the process outlined above. For a project as large as this the planning and QA phases were particularly demanding.
During the migration process we used the Migrate module and a large number of standard plugins it provides for managing the process. The initial migration process went relatively smoothly, given that there was a reasonable degree of remapping that took place. The next phase which involved fixing broken links and managing redirects was quite demanding. The process involved close work with the client to resolve issues around areas where URLs needed to be fixed.
Further, the analysis of the classes being used in the content threw up quite a number of issues for us. You would be surprised how many custom classes can be found in a site that is 10 years old. We found around 700 classes which were in use. Working out how to handle these classes is not a task to be underestimated!
A migration of this size and complexity does take a substantial amount of effort. At the end of the process the results are worth it. The client now is running a Drupal 9 site with uplifted content and functionality.
Conclusion
At Morpht we like to say that “Code is like fish and data is like wine.” Your code may eventually rot away but your content should improve with age. A site update and subsequent migration gives you the chance to improve both your code and content. The focus may be on the new site but it is vital to make sure that the content is not lost in the process.
Upgrading a site from Drupal 7 to Drupal 9 should be viewed as an opportunity. The upgrade process will open up the benefits of Drupal 9 and will ensure that your site is supported into the future. It will also give you the cache to revisit the site architecture and possibly uplift your content so that it is better organised to service the needs of your clients.
The migration process from Drupal 7 to Drupal 9 is not a trivial process. It is important to use automated tools where possible. The Migrate module is a powerful approach that allows covering most of the scenarios. Combining this with other utility scripts to heal and uplift the content makes sure that your site content can be migrated and improved during the process.
