Migration to Drupal

We start by separating what the legacy system stores from what the organization actually needs to manage. Discovery focuses on content intent, reuse patterns, editorial workflows, and downstream consumers (site rendering, search, APIs, reporting). From there we define Drupal content types, fields, taxonomies, and component patterns (often paragraphs or structured components) with clear ownership and constraints. We then produce a mapping specification that ties each source record and field to a target entity and field, including transformations (normalization, HTML cleanup, media relinking), reference rules, and translation handling. The model is reviewed with content architects and engineering to ensure it supports long-term evolution: predictable entity boundaries, stable identifiers, and minimal coupling to templates. Finally, we validate the model through early test migrations on representative datasets. This quickly reveals hidden edge cases such as implicit relationships, inconsistent field usage, or legacy “special cases” that need explicit modeling in Drupal or a controlled deprecation plan.

The migration approach is largely the same because both versions share the same core migration concepts and APIs. The key architectural decision is to implement migration code as maintainable modules and configuration that align with modern Drupal practices: dependency injection, configuration management, and clear separation between mapping logic and environment-specific settings. For Drupal 10 targets, we ensure the architecture is upgrade-ready by avoiding deprecated APIs and by keeping contributed module dependencies minimal and well-audited. For Drupal 11 targets, we validate module compatibility early and design the build pipeline and local development environment accordingly. In both cases, we treat the migration as part of the platform architecture: content model, URL strategy, caching implications, and integration contracts are designed to survive upgrades. The goal is that the migration does not create a “one-time codebase” that blocks future version upgrades or forces a re-migration later.

A cutover plan defines how the organization moves from the legacy CMS to Drupal with controlled risk. It typically includes: a content freeze window (or a strategy for limited publishing), a final delta import plan, DNS/routing changes, redirect activation, and verification steps that must pass before the platform is considered live. Operationally, we define runbooks for each step, including who executes it, expected duration, and rollback criteria. We also define acceptance gates such as reconciliation thresholds (entity counts, key field parity), URL/redirect coverage checks, and smoke tests for critical user journeys and integrations. For complex platforms, we may recommend phased cutover (by site section, language, or domain) or parallel run periods where the legacy system remains available read-only. The goal is to make cutover an operational procedure with measurable checks rather than a single high-risk event.

Repeatability comes from treating migrations as engineered pipelines rather than manual scripts. We implement migrations using Drupal’s Content Migration API with deterministic identifiers, idempotent behavior where possible, and structured logging. This allows the same migration to be executed in local, CI, staging, and production environments with consistent results. We also standardize execution via containerized tooling (for example Docker-based environments) and environment configuration management. Source extracts and staging databases are versioned or at least traceable so teams can reproduce a given run and compare outputs. Finally, we define verification reports that can be generated after each run: entity counts, missing references, field-level anomalies, and redirect coverage. These reports make it clear whether a run is acceptable and where mapping logic needs refinement, enabling iterative improvement without losing control of the process.

We start by identifying all consumers of content and the contracts they rely on: endpoints, payload shapes, field expectations, filtering rules, and state behavior (published/unpublished, language fallbacks). During target modeling, we ensure the Drupal entity model can represent the required data without forcing consumers to infer meaning from legacy artifacts. For REST and GraphQL, we validate schemas and responses early using migrated sample datasets. Where the legacy platform exposed fields differently, we either implement compatibility layers (for example computed fields or view modes) or coordinate controlled contract changes with consumer teams. We also validate non-functional requirements: caching behavior, pagination, rate limits, and authorization. Integration testing is treated as part of migration acceptance, not a post-launch activity, because API regressions often stem from subtle data differences introduced during mapping and transformation.

Search and downstream feeds are treated as first-class integration surfaces. We identify what systems consume content (search engines, internal search, syndication feeds, analytics pipelines) and what triggers indexing (webhooks, cron, queue workers, or external crawlers). During migration runs, we control indexing behavior to avoid unnecessary load and to prevent partial datasets from being indexed. Depending on the architecture, we may disable indexing during bulk imports and then run controlled reindex operations once reconciliation passes. We also validate that the migrated content supports the same discoverability semantics: canonical URLs, metadata fields, language variants, and structured relationships used for facets or related content. The goal is that search quality and feed correctness are validated as part of pre-cutover testing, not left to production tuning after launch.

Model drift is usually a governance problem expressed as a technical symptom. We address it by defining explicit ownership for content types and taxonomies, documenting the intent of key fields, and establishing rules for when new fields or types can be introduced. On the technical side, we use configuration management to keep content model changes reviewable and deployable through the same pipeline as code. We also recommend patterns that reduce ad-hoc field creation, such as reusable components and well-scoped taxonomies. Operationally, we align editorial and engineering workflows: change requests are evaluated against reuse, reporting, and integration impacts. The migration becomes a baseline with clear rationale, making it easier for teams to evolve the platform without reintroducing the inconsistencies that made the legacy system hard to migrate.

Handover focuses on making the migration and the resulting platform operable by internal teams. Typical artifacts include: the target content model documentation, mapping specifications, migration runbooks, and reconciliation/validation reports that define acceptance criteria. We also document how to execute migrations (commands, environment prerequisites, expected runtimes), how to interpret logs, and how to troubleshoot common failure modes such as missing references, malformed source data, or media import issues. If delta migrations are required post-launch, we document the operational procedure and constraints. For governance, we provide guidelines for evolving the content model safely, including how configuration changes are managed and reviewed. The goal is that teams can maintain and extend the platform without relying on undocumented migration knowledge or one-off scripts.

The most common risks are data ambiguity, hidden dependencies, and late validation. Data ambiguity occurs when the legacy system stores meaning implicitly (for example, a field used differently across sections) or when relationships are embedded in markup rather than modeled. Hidden dependencies include integrations, editorial workflows, and URL rules that are not captured in documentation. Late validation is a delivery risk: if reconciliation and editorial review happen only near cutover, teams discover systemic mapping issues when there is little time to correct them. This often results in scope reduction, launch delays, or acceptance of known defects. We mitigate these risks by running early test migrations, producing measurable reconciliation reports, and making integration contracts explicit. We also recommend defining cutover gates and rollback criteria upfront so operational decisions are based on evidence rather than pressure near launch.

Validation combines automated reconciliation with targeted human review. Automated checks typically include: entity counts by type, missing or null critical fields, referential integrity (broken entity references), translation completeness, media availability, and permission correctness. We also validate URL coverage and redirect rules, because broken paths are a frequent post-launch issue. We then run sampling-based editorial review on representative sections and edge cases. This is not a subjective “spot check”; it is guided by checklists tied to the content model and known risk areas such as embedded components, complex tables, or legacy shortcodes. Finally, we validate integration behavior using migrated datasets: API responses, search indexing, caching, and critical user journeys. Go-live readiness is defined by explicit acceptance thresholds and documented exceptions, so stakeholders understand what is complete, what is deferred, and what the operational plan is for any remaining deltas.

When documentation is limited, scoping relies on structured discovery and sampling. We begin with a content and integration inventory: enumerate content types, volumes, languages, media stores, user roles, and external dependencies. We then select representative samples that cover the breadth of patterns in the legacy system, including known “special cases.” From this, we define a migration backlog: mapping rules, transformations, and risk items. We also define what is in scope for parity (what must match exactly) versus what can be improved or normalized during migration. This avoids accidental scope creep where teams try to redesign everything while also migrating. We typically propose phased milestones: first migrate a small but representative slice end-to-end, validate the approach, then scale to full migration. This creates reliable estimates based on observed complexity rather than assumptions derived from incomplete documentation.

Collaboration usually begins with a short discovery phase focused on establishing facts and constraints. We start with stakeholder interviews (platform, content, operations) and a technical review of the legacy CMS, including content exports, database access where available, and an inventory of integrations and URL rules. We then produce a migration outline that includes: target platform assumptions (Drupal 10/11), a preliminary target content model direction, a mapping and pipeline approach, key risks, and a proposed validation strategy. This is paired with an initial cutover hypothesis (freeze window, delta strategy, rollback criteria) so operational planning starts early. Once the outline is agreed, we move into implementation with an iterative plan: build the pipeline, run test migrations, validate with reconciliation reports and editorial review, and refine until acceptance gates are met. This staged start reduces uncertainty while keeping the engagement aligned with delivery timelines and platform governance.