How to Create a Custom Drupal Migration from CSV to Paragraphs
Moving structured content from a spreadsheet into Drupal becomes more involved when each record contains flexible page sections. A CSV may hold titles, summaries, images, buttons, and repeated content blocks, while Drupal stores those blocks as Paragraph entities referenced by a node field. A reliable migration must therefore create the Paragraphs first, preserve their revisions, and then connect them to the correct parent content.
This guide presents a practical workflow for Drupal 9, 10, and 11 projects using the Migrate API, Migrate Plus, Migrate Tools, and a CSV source plugin. The examples suit a common Australian publishing setup, such as importing suburb landing pages, council information, or product content prepared by an agency in Sydney, Melbourne, Brisbane, or Perth.
| Content pattern | Suitable migration design | Main consideration |
|---|---|---|
| One CSV row contains one paragraph | One paragraph migration followed by one node migration | Simple source identifiers |
| Several paragraph rows belong to one node | Paragraph migration plus grouped node references | Stable parent keys are essential |
| A node contains different paragraph types | Separate migrations or a custom process plugin | Each type needs its own field mapping |
| CSV contains JSON or delimited block data | Custom source or process plugin | Validate and normalise the structure first |
Choose a migration shape
Start by deciding what one row represents. The easiest arrangement has one CSV row for each Paragraph and includes a stable parent key, such as page_code. A second CSV contains the parent nodes, or the same source can be used by two migrations when its columns contain both page and component data.
For example, a content file might contain page_code, title, paragraph_type, heading, body, and sort_order. The value page_code should identify the destination node, while a combination such as page_code and sort_order can identify each component. Avoid using the spreadsheet row number as the permanent key because editors may sort or re-export the file.
A useful model for a local directory site might have one page for bondi-beach-nsw and three Paragraphs: an introductory text block, a services block, and a call-to-action block. Australian state abbreviations, postcodes, and suburb names should be preserved as data rather than inferred from the title. “Richmond” could refer to places in several states, so a unique source code is safer than a name.
Prepare Drupal and the source CSV
Install the required modules with Composer. The exact CSV module depends on the project and Drupal version, but a typical setup includes Migrate Plus, Migrate Tools, Paragraphs, and a maintained CSV source extension.
composer require drupal/migrate_plus drupal/migrate_tools drupal/paragraphs
drush en migrate_plus migrate_tools paragraphs -y
Create the Paragraph types and fields before importing anything. If the content model includes Text, Image, and Call to action Paragraph types, confirm their machine names and field storage. A field named “Body” in the administration interface may have a machine name such as field_body, while the node field may be field_content.
Save the CSV as UTF-8 and use a consistent delimiter. Excel exports can introduce curly quotes, unexpected line breaks, or a byte-order mark in the first header. Test Australian content such as Cairns, Wollongong, Hobart, and Darwin, along with apostrophes in names and HTML entities. Date values should use an unambiguous format such as 2025-03-01, rather than a mixture of 01/03/2025 and 3/1/25.
Define the Paragraph migration
Place migration configuration in a custom module, commonly under config/install for installation-time configuration or a migrations directory loaded by Migrate Plus. The paragraph migration needs a unique source ID and a destination of entity:paragraph.
A simplified YAML definition might look like this:
id: imported_paragraphs
label: Import content paragraphs
migration_group: website_content
source:
plugin: csv
path: modules/custom/site_migrate/data/content.csv
header_row_count: 1
keys:
- paragraph_key
column_names:
0: paragraph_key
1: page_code
2: paragraph_type
3: heading
4: body
5: sort_order
process:
type:
plugin: static_map
source: paragraph_type
map:
text: text
cta: call_to_action
field_heading: heading
field_body:
plugin: markdown_to_html
source: body
destination:
plugin: 'entity_reference_revisions:paragraph'
default_bundle: text
The exact process plugins depend on the field types and installed modules. A static_map is helpful when CSV values are business-friendly labels such as Text block, while Drupal expects a machine name. For formatted text, map the source into the field’s expected structure and choose a text format explicitly. Never allow imported markup to become unrestricted HTML simply because the CSV contains tags.
If several Paragraph bundles share one file, a dynamic bundle process may be needed, or separate migrations can be easier to maintain. Separate migrations are often clearer when the fields differ substantially. The source key must remain unique across all rows, and the migration should include migration_dependencies only when another migration must run first.
Import parent content and references
The node migration uses the same parent key and looks up the Paragraph entities created by imported_paragraphs. A basic node configuration can map the title, a source identifier, and a single Paragraph reference:
id: imported_pages
label: Import landing pages
migration_group: website_content
source:
plugin: csv
path: modules/custom/site_migrate/data/pages.csv
header_row_count: 1
keys:
- page_code
column_names:
0: page_code
1: title
2: summary
3: paragraph_key
process:
title: title
field_source_code: page_code
body:
plugin: get
source: summary
field_content/target_id:
plugin: migration_lookup
migration: imported_paragraphs
source: paragraph_key
field_content/target_revision_id:
plugin: entity_revision_lookup
migration: imported_paragraphs
source: paragraph_key
destination:
plugin: 'entity:node'
default_bundle: landing_page
migration_dependencies:
required:
- imported_paragraphs
For an entity reference revisions field, Drupal needs both the entity ID and the revision ID. A plain migration_lookup is commonly sufficient for the target entity, but the revision lookup process plugin and its availability should be checked against the project’s Drupal and module versions. If the lookup plugin is unavailable, inspect the generated Paragraph revisions and use a project-specific process plugin rather than assigning revision IDs by assumption.
Run the Paragraph migration before the node migration. The dependency helps Migrate Tools order them, but it does not repair missing source keys. If the node field allows unlimited values, one source row needs to produce an array of references. That usually requires a grouped source, a sub_process, or a custom process plugin.
Handle grouped rows and rich text
A common CSV design stores one row per component:
paragraph_key,page_code,paragraph_type,sort_order,heading,body
home-01,home,text,1,Welcome,Our services cover regional Queensland.
home-02,home,cta,2,Talk to us,Contact the team for a quote.
The Paragraph migration can create both rows, but the node migration must collect home-01 and home-02 in the correct order. A migration source plugin that groups rows by page_code is the cleanest option. Another approach is a custom process plugin that queries all source rows for the current parent and returns ordered target and revision IDs.
Do not rely on CSV row order unless the source plugin explicitly preserves and sorts it. Use sort_order as a numeric value, validate duplicates, and define what happens when two components have the same position. This matters for pages assembled by content teams across different offices, especially when a spreadsheet is edited in Australian Eastern Time and later exported by a vendor in another time zone.
Rich text needs its own rules. Decide whether the CSV contains plain text, Markdown, or a restricted HTML subset. Convert Markdown through an approved text format, strip dangerous attributes, and map links and images deliberately. Relative image paths in a spreadsheet will not automatically become Drupal media entities; they need a separate file or media migration, followed by a lookup from the Paragraph field.
Add custom logic where configuration stops
YAML is effective for direct field mappings, defaults, lookups, and simple transformations. A custom source plugin becomes worthwhile when the CSV contains nested JSON, repeated columns such as button_1_label and button_2_label, or multiple logical records inside one line. The plugin can normalise that input into rows with stable IDs before the process pipeline runs.
A custom process plugin is useful for tasks such as converting Australian phone numbers, normalising state names, or generating a Paragraph reference list. Keep those transformations deterministic. For instance, convert 02 9876 5432 to a consistent display or storage format, but do not silently change a supplied postcode. Validation should report a bad value rather than turning it into an apparently valid one.
When the migration contains complicated business rules, document them beside the code. A short note explaining why ACT and NSW are mapped to particular taxonomy terms can prevent confusion during a later content refresh. Developers looking for broader Drupal implementation perspectives can also browse Oscar David Sanchez for related technical context.
Run, test, and troubleshoot
Use Drush to inspect and execute migrations:
drush migrate:status
drush migrate:import imported_paragraphs
drush migrate:import imported_pages
During development, import a small CSV containing one page and each Paragraph type. Check the node’s reference field, rendered order, text format, revision IDs, image relationships, and cache output. Then test an update by changing one source value and rerunning the migration. The existing entity should be updated when the source ID and destination identifiers are configured correctly.
Useful commands include migrate:messages for errors and migrate:rollback for removing test output. Rollbacks should be used carefully on shared environments because they may remove content created by the migration. Take a database backup and test in a staging environment before running a large import for a production site serving customers in Melbourne or a national organisation with offices across Australia.
Typical failures include “missing migration lookup,” which usually means the Paragraph migration did not run or the source key does not match; an empty Paragraph field, which can indicate an incorrect machine name; and revision errors caused by using an entity ID where a revision ID is required. Also check file permissions, CSV encoding, line endings, and whether the PHP process can read the configured path.
Make the migration repeatable
A production-quality migration should be safe to run more than once. Use immutable source identifiers, configure unique keys, and decide whether changed source data should update existing nodes and Paragraphs. Avoid hard-coding destination entity IDs because content may already exist on staging or production.
Keep the CSV outside the public web root when it contains unpublished information. Store migration configuration in version control, and keep environment-specific paths in settings rather than editing YAML directly on the server. A deployment pipeline can then import configuration, validate the migration status, and execute the job under controlled conditions.
For large files, process in batches and monitor memory usage. Disable unnecessary hooks only when their impact is understood, and rebuild caches after the import if rendered output appears stale. Record the source filename, import date, row count, and rejected rows so editors can reconcile the Drupal result with the original spreadsheet. Updates about Drupal development practices and community discussion are collected in Drupalwoo updates, which can be useful when maintaining the migration over time.
The strongest CSV-to-Paragraph migrations treat the spreadsheet as a structured data source rather than a visual document. Stable keys, explicit Paragraph bundles, revision-aware references, controlled text formats, and repeatable tests turn a fragile one-off import into a maintainable part of the Drupal project.