Import Content with Simple Steps: Drupal Guide
Andrea Corda
Founder @GeoNovation - We provide specialized high-quality software development specialized in Drupal, Backend, and Cloud Applications.
Migrate Plus of Drupal
When we are developing Drupal website, specially migrating from Wordpress or other CMS, at the end of the development process, many times it is required to perform data migration from the old website to the new one.
Typical data to import are content, taxonomies with their relationship, and attachment files, and to do this, drupal offers a complex module famous for its lack of documentation, called Migrate Plus that extends the functionality of the native Drupal Migrate API.
This module provides a powerful and flexible framework for importing data from external sources into Drupal and it is a popular choice for migrating data from other websites or systems, and it can handle a wide variety of data types, including files and attachments.
Lack of Documentation
One of the challenges of using Migrate Plus is the lack of documentation. The module is well-written and has a large community of users, but the documentation can be difficult to find and understand. This can make it difficult to get started with Migrate Plus and to troubleshoot problems.
Problems with Importing External Files
One of the most common problems with Migrate Plus is importing external files, such as images and documents.?
In this guide, I want to provide a clever solution we have been using to perform migration from other website in Wordpress to copy the remote PDF attachments, import locally and assign to a content type.
Prepare the environment - Installation of Migrate Plus
To perform the migration we will need the following modules in the case we will import from a CSV file: ? ? ?
<pre>
composer require 'drupal/migrate_source_csv:^3.7'
composer require 'drupal/migrate_plus:^6.0'
drush en migrate_plus migrate_source_csv
</pre>
Creation of an importer module
To perform migrations we will have to create a specific module that contains configuration files explaining how to read the CSV.
To create the module we create a new folder: in /web/module/custom/<module_name> that in this case for convenience we will call “wp_migrate”?
Wp_migrate will contain the following files: Wp_migrate.info.yml ? -> Module basic definition and information
Wp_migrate.module ? -> Hooks and functions used by the module.
Wp_migrate.services.yml? -> Registration to the module for the migration services
wp_migrate.info.yml
Wp_migrate.services.yml
Wp_migrate.module?
This file doesn’t have extensions but it is a PHP file read by drupal that contain generic and basic hooks for the module.
This hook is really important because makes us easier for each migration, specified by the ID ( import_lesson ) the path of the source adding automatically the prefix of the module, keeping relative paths for the CSV files.
Upload and configure the CSV the CSV files
Inside the module folder we will create a folder called “artifacts” in which we will upload the csv files
The structure of the csv file ( lessons.csv ) we will use as example is the following:
With the following columns:
Id
Date
Title
Countries
Content
Tags
Year
Theme
Project_name
Project
attachment_pdfs
And we will add the configuration for the report inside the folder? /migrations? has we have registered in the wp_migrate.services.yml
The ID is the most important value because it is unique and will be used by the system to run the migration: should follow the machine name structure in Drupal.
The Source includes the information to read the CSV plugin and the path is absolute starting from the module folder, as it is prefixed by the hook precedently setup. We can even add a mapping for the columns if required.
The IDs established the primary keys, to avoid duplicated values, which can be helpful when we import hierarchical taxonomies.
The destination indicate which kind of element are creating, if node or taxonomy and the bundle.
Inside the process block, we will have a mapping from the Drupal fields to the CSV columns. We can map directly the CSV fields or we can perform transformations using some plugins
Associate a reference taxonomy with an existing taxonomy or create a new taxonomy term.
Migrate Plus offers two plugins that allow to manage the entity references.?
In this case, we read the tags and the theme and we perform “an explode” function in order to manage multiple tags or themes, and the explode will return an array of IDs calculated by entity_lookup or entity_generate.
Associate a reference field to another content type
To connect an content type entity with another content type entity we can use the same plugins, but instead of taxonomy terms we should use “node” as entity_type.
Download an external file as a File Entity and associate it with the content.
When in the CSV we have external PDFs files, like in the column “attachment_pdfs” we should create File entity ( managed by File API in Drupal ).
We can create file entities for remote files, but in this case can be problematic in the case the external resource is not any more accessible, so, for this reason, we should import the file in a local public folder, and then return the entity ID created.
We have created a specific plugin in order to perform this operation inside the wp_migrate module.
Notice that in the first heading of the document we are defining the component to be readed by Migrate Plus with the declaration? @MigrateProcessPlugin ( id = “download” ) that we will use in the yml of the importer.
Main Migrate Plugins
The main plugins can be concatenated just with an YML array as we saw before using the explode plugin.
The main are:
More documentation is available here: https://www.drupal.org/docs/8/api/migrate-api/migrate-process-plugins/list-of-migrate-process-plugins
Use migrate and perform migrations with Drush.
The main commands to be used with Drush are:
Conclusion
Successfully importing content with external attachments in Drupal using Migrate Plus requires a well-structured approach that ensures data integrity, scalability, and maintainability. By leveraging Migrate API, Migrate Plus, and Migrate File modules, developers can efficiently transfer structured content while ensuring that attachments—whether images, PDFs, or media files—are properly linked and accessible.
Key Takeaways:
? Understanding Source Plugins – Using the correct external data sources ensures a seamless migration process.
? Efficient File Handling – Properly configuring file destinations prevents broken links and missing assets.
? Performance Optimization – Large-scale migrations benefit from batch processing and automated error handling.
? Security & Compliance – Ensuring that file paths and access permissions align with Drupal’s security best practices.
As Drupal continues to evolve, migration strategies will become even more critical, especially for organizations transitioning from legacy systems or integrating third-party content sources. Implementing these best practices will future-proof your Drupal site, ensuring seamless content management and a superior user experience.
Future-Proof Your SEO Strategy with Geonovation.it
The rules of SEO are always changing. Are you prepared to keep up?
At Geonovation.it, we specialize in Drupal SEO optimization, development, and digital strategy to help businesses navigate the complexities of search engine visibility. Whether you need a complete SEO audit, performance optimization, or structured content strategy, we’re here to help.
?? Contact us today to discover how we can elevate your Drupal site’s search rankings and digital impact