How to migrate from Drupal to a headless CMS
Move Drupal to headless delivery or Payload with a field and reference map. Preserve media, translations and approved retail answers through cutover.
- Published
- Last updated
To migrate from Drupal to a headless CMS, either keep Drupal behind a new frontend or transfer its content entities into a replacement such as Payload. Retail teams must map fields and references before moving records. Themes, module behaviour and editorial permissions need separate implementation.
The main risk is carrying the wrong version of retail guidance into the new site. A complete record count can still hide missing translations or a draft published as approved advice.
Choose decoupled Drupal or a new content owner
Keep Drupal as the content owner when its editing and approval workflow already suits your team. A decoupled frontend reads Drupal content through an application programming interface (API). Editors continue working in Drupal, while developers rebuild public rendering and preview connections.
Replacing Drupal with Payload also moves responsibility for the content model. You transfer entity values and relationships into destination collections, then rebuild the rules that govern their use. This branch fits teams that want a different structured editing model and can maintain the replacement.
For example, a buying guide might reference category terms, product identifiers and translated media captions. Copying its body alone loses those relationships. Decide whether that rebuilding work solves an editorial problem before replacing a working content service.
Inventory entities and access before export
Inventory each entity type and bundle before requesting its records. A bundle is a subtype, such as a buying guide within the node entity type. Drupal’s JSON:API overview documents separate resource URLs for each type and bundle.
Record the following from your estate:
- Bundle and field machine names, field types, required values and allowed cardinality.
- Entity identifiers, taxonomy vocabularies and ordered references between records.
- Media entities, original files, captions, alternative text and private-file restrictions.
- Languages, translation status and language-specific references.
- Published status, moderation states and the revision selected for public delivery.
- URL aliases, redirects, menus and links embedded in rich text.
- Custom modules, rendering filters and integrations that change what readers see.
Keep a separate inventory for user roles and permission rules. Exporting an author reference does not recreate that author’s authority in Payload.
Create a recoverable source backup before extraction. Drupal’s backup guidance covers the database, uploaded files, site settings and customised software. Restore a copy in an isolated environment before relying on it for recovery.
Extract every permitted page and language
Use a migration account with read access to the intended content and files. Give it access to unpublished revisions only when those belong in the private transfer. Keep its credentials on the server and separate from the public frontend.
With core JSON:API enabled, fetch each required bundle through its documented endpoint, such as /jsonapi/node/article. Keep the resource UUID, attributes and relationship identifiers together. Extract referenced records as well as their identifiers.
Follow each response’s next-page link until it disappears. Drupal’s pagination instructions explain that access checks can produce a short page even when more records remain. A short response is not a reliable stopping condition.
Define which revisions the export includes. Drupal’s revision documentation distinguishes default versions from working copies and documents read support for node and media revisions. A moderated working copy can differ from the default revision. Retain historical revisions in the source backup when your transfer includes only approved content.
Extract each required language using the site’s configured language negotiation. Drupal’s translation documentation describes negotiation and fallback. Record the returned language so a fallback does not become a second copy labelled as a translation.
Build and apply the transfer matrix
Map every source field to a destination field before importing content into Payload. Keep the Drupal UUID in a dedicated source identifier field, then maintain a source-to-destination ID map. A destination database ID can change without breaking your record of origin.
The following fictional retailer moves a buying-guide bundle into Payload. The names illustrate a mapping, not a built-in Drupal importer.
| Source item | Transfer method | Retained values | Loss or separate work | Manual check |
|---|---|---|---|---|
| Guide node | Transform attributes into a guides record | Source UUID, title, summary and approved status | Drupal revision history stays in the retained source | Match each destination record to its approved source revision |
| Body field | Convert stored text into the destination rich-text format | Paragraphs, headings and supported links | Drupal text filters and custom embeds need replacement | Compare rendered advice and embedded content |
| Category reference | Create taxonomy records, then map relationship IDs | Term names, hierarchy and reference order | Vocabulary rules need destination configuration | Follow each guide’s category reference |
| Media reference | Acquire original files and create upload records | File content, alternative text and captions | Image styles and protected delivery need rebuilding | Open the file without relying on Drupal hosting |
| Translation | Write mapped fields into the configured destination locale | Language-specific values and approved references | Fallback and moderation rules need explicit configuration | Compare each locale with its own source |
| Alias | Retain the path or create an old-to-new URL mapping | Original public address and destination | Redirect handling belongs to the delivery layer | Request each old URL and inspect its final page |
Use this order for the replacement branch:
- Configure Payload collections and locales from the approved mapping. Add source identifiers and publication controls before creating records.
- Transform a small sample and reject unsupported rich text for manual repair. Keep the original value alongside the transformation record.
- Create independent taxonomy records and upload the acquired media files. Save each returned destination ID against its Drupal source ID.
- Create guide records with Payload’s documented Local API operations, using the configured collection and transformed data. Upload collections accept a local file path.
- Resolve guide relationships through the ID map. Use a second update pass for circular references, keeping incomplete records unpublished.
- Read the resulting records back and reconcile failures before repeating the import. Look up the source identifier before creating another record to avoid duplicates.
Payload’s Import Export plugin is another branch once you have transformed the source into its supported CSV or JSON input. It is not a direct Drupal database or theme importer. Use the Local API branch when your conversion needs explicit media creation or several relationship passes.
Local API operations bypass access control by default. Where the migration must obey a configured user’s permissions, pass that user and set overrideAccess to false. Review hooks before a bulk run so imported content does not trigger unintended notifications or downstream publication.
Recreate moderation transitions and editor roles separately. Drupal themes and contributed-module behaviour remain software work even when their source fields appear in the export.
Check references and approved publication
Validate the imported content against the agreed export scope before changing public delivery. Compare counts by bundle, publication state and language. Count unique source IDs separately from locale values so translated records do not inflate the expected total.
Sample long rich text and every custom content pattern. Check tables, embedded media, text-filter output and internal links in rendered pages. Open original files and confirm that protected media remains protected. Exercise both language switching and language-specific references.
For the fictional retailer, suppose the accepted manifest contains 40 guides and 12 translated versions. Expect 40 mapped guide identities and 12 corresponding locale versions. Every required category and media reference must resolve. Exclusions need a recorded reason outside the public site.
Follow a product-guide correction to the customer
Choose one approved guide correction with a clear expected answer. For example, change a fictional jacket guide from recommending tumble drying to recommending air drying. Keep a pending editorial draft with different wording to check the publication boundary.
Read the approved destination record, then open the storefront guide through its public URL. Confirm that it shows air drying and that the draft remains private. Follow the same guide into the documents or feed used by your shopping-answer service.
Refresh that service’s content using its configured update process, then ask a new care question and inspect the retrieved source. The answer must use the approved guide. A response that sounds correct without the right source is insufficient evidence.
Remove the superseded Drupal URL or export from the active retrieval sources. Check duplicate document uploads and cached copies as well. Withdraw the destination guide in the test environment and confirm that the service stops retrieving it. That check catches an old source still supplying withdrawn advice.
Test every changed URL against the redirect mapping. A redirect must reach the intended guide in the correct language, without a loop or an unrelated home-page fallback.
Change over and retain recovery options
Assign a named owner to each cutover dependency before opening the change window. The content owner approves the final versions and controls the editing freeze. Developers own the final extraction and ID map. Operations staff own delivery routing and credentials, while support staff receive the failure symptoms and escalation contacts.
Pause source edits briefly or capture an agreed final set of changes. Import those changes, repeat the affected checks and switch the frontend and shopping-answer sources together. Keep public read credentials separate from import credentials. Revoke temporary migration access after acceptance.
For decoupled Drupal, the return route is the retained Drupal-rendered frontend and its previous delivery configuration. For a replacement, retain the running Drupal site, its entities and media, plus the verified backup. Restore the previous routing and retrieval configuration if the replacement fails acceptance.
Before returning, reconcile edits made in Payload after the freeze. Map those changes back deliberately or preserve them for re-entry. A routing reversal cannot convert a changed schema or recover new editorial work automatically.
Keep the old delivery configuration and source copies until the agreed recovery period closes. Send unresolved extraction problems to the Drupal maintainer with the bundle and permission context. Send destination failures to the Payload maintainer with the affected collection and sanitised error details. Give each issue an owner before resuming routine editing.
Give your store its own shopping agent
Customers ask in their own words. Your agent finds, compares and checks out from your catalogue, right on your site.