A CMS migration sounds like a single project: export content from System A, import into System B, update templates, done. In practice, migrations fail for a more mundane reason: content is messy. Fields are overloaded, “temporary” workarounds become permanent, and multiple teams quietly use the same field for different purposes.
The way to reduce risk is to stop thinking of the migration as “moving pages” and start treating it as “mapping data.” A field-by-field approach makes the work visible, testable, and easier to hand off between engineering, content, and operations.
This post describes a method you can use whether you’re moving from an old CMS to a new one, consolidating multiple sites, or reorganizing a content system to support new templates and workflows.
Why CMS migrations go sideways
Most migration pain is predictable. The symptoms tend to look like “missing images,” “broken URLs,” or “random formatting,” but the causes are usually structural.
- Implicit meaning. A field like “Summary” might be used as a meta description, an email snippet, and a landing page intro. If you map it to only one destination field, two uses break.
- Hidden dependencies. Editors depend on ad-hoc patterns (like putting special tags in the body) because the old CMS never had a proper field for them.
- Inconsistent content types. “Article” might include news, evergreen guides, press releases, and event pages, all with different expectations.
- URL changes without a redirect plan. Even if SEO isn’t your focus, users and internal links still rely on stable paths.
A field-by-field migration method doesn’t eliminate these issues; it forces you to discover them early, while you can still decide what to standardize, what to preserve, and what to retire.
Step 1: Inventory what you actually have
Start with an inventory that’s specific enough to make decisions, but not so detailed that you never finish. The output you want is a list of content types and a count of items per type, plus a quick scan of “special cases.”
Minimum viable inventory
- Content types: pages, posts, products, docs, authors, categories/tags, media assets.
- Fields per type: title, body, excerpt/summary, slug, publish date, author, taxonomy, SEO fields, featured flags, etc.
- Volumes: item counts and approximate media counts.
- Shape issues: duplicate slugs, empty fields, wildly long titles, HTML embedded where plain text is expected.
As you inventory, write down “promises” that the current system makes to the outside world. For example: URLs that must keep working, a blog index that assumes publish dates exist, or a template that expects a hero text and a CTA field.
If you have multiple sites or locales, include them explicitly. Migrations often go wrong when “site” is treated as a filter rather than a core attribute that affects URL structure, navigation, and permissions.
Step 2: Define a canonical content model
A canonical model is the “source of truth” shape you want your content to have during and after the move. It’s not necessarily the destination CMS schema; it’s a neutral structure that makes mapping easier and exposes gaps.
Think of it as a contract between teams: content strategy defines what fields should exist, engineering defines what fields are required for rendering and integrations, and operations defines what fields are needed for day-to-day publishing.
For each content type, decide:
- Required fields vs optional fields. “Required” should mean “the site breaks or looks wrong without it,” not “nice to have.”
- Single vs multiple values. One author or many? One category or many? Make the multiplicity explicit.
- Field format. Plain text, rich text, markdown, structured blocks, references, arrays.
- Ownership. Who maintains it: editorial, marketing ops, engineering?
This is also the right time to decide what you will not migrate. Old landing pages, expired campaigns, and test content inflate scope and create edge cases. If you can’t delete them, label them as archived and keep them out of primary navigation.
Key Takeaways
- Reduce migration risk by treating the project as data mapping, not page copying.
- Inventory content types, volumes, and special cases before deciding on tooling.
- Create a canonical model so “what the content means” is defined independently of any CMS.
- Use a mapping matrix with explicit rules for transforms, defaults, and exceptions.
- Migrate in stages with repeatable runs and clear acceptance checks.
Step 3: Build a field mapping matrix
The mapping matrix is the heart of the method. It’s a shared document (often a spreadsheet) that states, field by field, where data comes from, where it goes, and what needs to happen in between.
A good mapping matrix removes ambiguity. If the migration script fails, the question becomes “which mapping rule was wrong?” rather than “why does the new site feel off?”
What to include in the matrix
- Source: content type and field name in the old CMS.
- Destination: content type and field name in the new CMS.
- Transform: rules like “strip HTML,” “convert to markdown,” “split by commas,” “lookup author ID.”
- Default behavior: what happens when the source is empty or invalid.
- Validation: how you’ll verify correctness (length limits, allowed values, required refs).
- Notes / exceptions: known edge cases and how to handle them.
Here’s a compact example of the kind of structure you want (conceptual, not code):
ContentType: Article
- title: old.title_text -> new.title (required, trim whitespace)
- slug: old.slug -> new.slug (lowercase; ensure uniqueness)
- body: old.html_body -> new.richText (sanitize; preserve headings)
- excerpt: old.summary -> new.excerpt (fallback: first 160 chars of body)
- author: old.author_name -> new.authorRef (lookup by canonical slug)
- tags: old.keywords_csv -> new.tags[] (split; normalize; dedupe)
- seoDescription: old.summary -> new.metaDescription (max 160 chars)Notice what this does: it exposes when one source field feeds multiple destination fields (like summary feeding excerpt and meta description), which is a common pattern that should be documented rather than discovered later.
When disagreements come up (“Should excerpt be auto-generated or editorial?”), put the decision in the matrix. The matrix is not just technical documentation; it’s the shared set of decisions that makes the migration repeatable.
Step 4: Run migrations in stages (not all at once)
A migration run should be something you can repeat, compare, and roll forward. Treat it like a pipeline: input data + mapping rules + transforms + validations = a result you can inspect.
A staged run plan that works for small teams
- Dry run on a small slice. Migrate 20–50 representative items across key types (including weird ones). Don’t aim for completeness; aim for learning.
- Fix the schema and mapping. This is where you change fields, add missing relationships, and refine transforms based on what you saw.
- Full run into a non-production environment. Migrate everything, generate a report of errors/warnings, and do structured QA.
- Content freeze window (if needed). If your content changes frequently, define a freeze period or a delta plan for items changed after the export.
- Final run + cutover. Execute the final import, validate, enable redirects, then switch traffic.
Structured QA is more effective than random browsing. Pick checks that match your promises from the inventory step:
- Counts: item counts by type match expectations (with documented exclusions).
- Required fields: no missing titles, slugs, or other required data.
- URL behavior: a sample set of old URLs resolves correctly (either same URL or redirected).
- Rendering: headings, lists, and quotes render consistently; no double-escaped HTML.
- Search and filters: tags/categories behave as intended; no taxonomies explode into duplicates.
If you can only do one thing for peace of mind: establish a “golden set” of 25–50 URLs/content items that must look right, and use them as a regression suite for every run.
Step 5: Plan for life after migration
The migration is not the finish line; it’s the start of operating a new system. Many teams discover late that the new CMS has a different editorial rhythm, permission model, or preview process.
Before cutover, define a small operations checklist:
- Roles & permissions: who can publish, who can edit schemas, who can manage taxonomies.
- Editorial conventions: slug rules, title casing, tag naming, excerpt length, and how to handle updates vs new posts.
- Redirect ownership: where redirects live and who is allowed to add or change them.
- Backups and exports: how to export content for safety or downstream systems.
- Ongoing cleanup: a cadence for removing unused fields, merging duplicate tags, and archiving outdated content.
Finally, keep the mapping matrix. Even after the migration, it becomes valuable documentation: it tells you where fields came from, what transforms were applied, and why the system looks the way it does. That’s useful when you onboard new editors, build automations, or run your next redesign.
Conclusion
A calm CMS migration is less about the perfect tool and more about making decisions explicit. Inventory what exists, define what you want, map fields with clear rules, and run the process in repeatable stages with measurable checks.
If you do those things, “migration” stops being a one-time fire drill and becomes a controlled data transformation you can reason about—and fix—without panic.
FAQ
Do we need to keep URLs exactly the same?
Not always, but you need a plan. If URLs change, implement redirects and verify a representative sample. Also consider internal links: even if redirects exist, updating key internal references reduces long-term maintenance.
Should we migrate old drafts and unused content?
Usually no. Drafts and abandoned pages add scope and increase edge cases. If you need them for record-keeping, migrate them into an “Archived” state or a separate space that doesn’t affect navigation or search defaults.
How do we handle rich text differences between CMS platforms?
Assume you’ll need a transformation layer. Decide what you’re preserving (headings, lists, links) and what you’re simplifying. Test a “worst case” set of content early, because formatting issues often look small but take time to correct at scale.
What’s the smallest team setup that can still do this well?
You can do a solid migration with one engineering owner, one content/ops owner, and one decision-maker for tradeoffs. The key is shared artifacts (inventory + canonical model + mapping matrix) so decisions don’t live only in someone’s head.
For more posts on systems and publishing operations, browse the Archive or return to the Home page.