CMS Migration Redirect Map: A Practical Build Guide

A redirect map is a product decision, not a list of old URLs

A CMS migration redirect map defines what should happen when a person or search system requests an existing URL after the new site launches. The spreadsheet is simple. The decisions behind it are not.

During my WordPress-to-Contentful migration work for TaxAct, the publication served more than 500,000 monthly unique visitors. That scale made one principle clear: a redirect is successful only when it preserves the intent of the original path. Sending every retired article to the homepage may eliminate a visible error, but it does not give the visitor the answer they expected.

This guide turns redirect planning into a repeatable workflow. Start with the copyable redirect-map CSV, then adapt the columns and validation rules to the platform that will execute the redirects.

Build the source URL inventory from more than one signal

No single export is guaranteed to contain every valuable URL. Combine sources and preserve where each path came from.

Useful inputs include:

• CMS entries and current routing fields;
• XML sitemaps;
• analytics landing-page reports;
• search performance exports;
• crawl data;
• server or edge request logs when available;
• existing redirect configuration;
• internal-link exports;
• campaign and email destination lists;
• stakeholder lists of important legacy pages.

Normalize the inventory before mapping it. Decide how to represent protocol, hostname, trailing slashes, capitalization, encoded characters, query parameters, and fragments. Store the original value separately when normalization could hide an exception.

Deduplicate by the version of the URL the redirect system will actually match. Two spreadsheet rows that look different can become the same request after lowercase or trailing-slash normalization.

Give every source URL an explicit disposition

Each source path needs one of four decisions:

1. Preserve: the final URL remains the same and should return the intended content.
2. Redirect: a relevant replacement exists at a different URL.
3. Consolidate: multiple old pages intentionally point to one stronger destination that satisfies their shared intent.
4. Retire: no appropriate replacement exists, so the request should return the team’s approved not-found or gone behavior.

Do not use “redirect” as the default merely because it feels safer. An unrelated destination can confuse visitors and hide gaps in the content plan.

Record the reason for the disposition. “Slug changed during model redesign” is reviewable. An unexplained destination is difficult to validate when the map contains hundreds or thousands of rows.

Map destinations by intent and content equivalence

Start with exact replacements:

• the same article at a new path;
• a renamed service with equivalent scope;
• a consolidated category page that still answers the same navigation need;
• a new canonical version of duplicated content.

When no exact replacement exists, compare:

• audience;
• question or task;
• subject and scope;
• search intent;
• stage of the customer journey;
• expected next action.

A close keyword match is not enough. An old implementation tutorial should not automatically redirect to a high-level service page just because both mention the same platform.

If several source URLs consolidate into one destination, document why the target is a genuine replacement. This makes editorial review possible and prevents convenience from masquerading as relevance.

Separate pattern rules from reviewed exceptions

Large migrations usually need both.

A pattern rule can handle predictable changes, such as:

• removing a fixed directory;
• changing a locale prefix;
• converting a known date structure;
• renaming a consistent content-type segment.

Exceptions handle paths where the destination cannot be derived safely. Keep them visible rather than adding increasingly clever pattern logic that nobody can audit.

For every pattern, define:

• the exact match scope;
• whether matching is case-sensitive;
• captured values and destination construction;
• query-string behavior;
• exclusions;
• precedence relative to other rules;
• representative passing and failing examples.

Run the pattern against the full inventory before launch. Compare the generated destination with the approved map and flag collisions, missing captures, unexpected matches, and paths claimed by more than one rule.

Decide how query parameters and fragments behave

Some parameters are tracking-only and can be preserved or removed according to the analytics plan. Others change the content, filter state, language, or campaign destination and require explicit handling.

For each URL family, record whether to:

• preserve every parameter;
• preserve an approved allowlist;
• transform a parameter into the destination path;
• discard known tracking parameters;
• route important parameter combinations individually.

Fragments are not sent to the server, but they still matter to visitors. If an old campaign linked directly to a section, check whether an equivalent anchor exists on the destination and update owned links where possible.

Avoid making a universal query-string rule without reviewing how the old application used parameters.

Prevent redirect chains, loops, and collisions

Every source should resolve directly to its final destination.

If an existing rule sends A to B and the migration sends B to C, update A to point directly to C. Chains add latency, complicate debugging, and create more opportunities for a future rule to break the path.

Automated validation should flag:

• a destination that is also a redirect source;
• a source that maps to itself after normalization;
• cycles of any length;
• multiple rules claiming the same source;
• a preserved URL that is also listed for redirect;
• destinations outside the approved host list;
• destination URLs that do not return the expected public result.

Keep redirect generation deterministic. The same approved map should produce the same configuration, and the generated artifact should be reviewable before deployment.

Use a redirect map with reviewable columns

The downloadable template includes:

• source_url: the requested legacy path;
• destination_url: the final replacement, blank when preserved or retired;
• disposition: preserve, redirect, consolidate, or retire;
• status_code: the intended response when applicable;
• match_type: exact, pattern, or exception;
• query_handling: preserve, allowlist, transform, or discard;
• reason: why this outcome preserves intent;
• source_signal: where the URL was discovered;
• owner: the person responsible for the decision;
• priority: a review order based on business or audience importance;
• test_status: not tested, passed, or failed;
• notes: constraints and follow-up.

Add platform-specific identifiers or rule names when they improve traceability. Avoid columns that nobody will maintain.

Download the CMS migration redirect-map CSV and import it into the team’s spreadsheet or data-review tool.

Test the map before changing production traffic

Test the map as data first, then test it against a deployable environment.

Dataset validation

• required fields are present;
• source paths are unique after normalization;
• disposition values are valid;
• redirect rows have destinations;
• preserve and retire rows follow their expected rules;
• pattern examples produce approved destinations;
• chains, loops, collisions, and unsafe hosts are absent.

Environment validation

• the source returns the expected status;
• the location header points directly to the final destination;
• the destination resolves successfully;
• the rendered destination satisfies the original intent;
• query behavior matches the decision;
• headers, caches, and edge rules do not change the result unexpectedly.

Review a risk-based sample manually: the highest-traffic pages, important conversion paths, top search landing pages, complex parameters, old exceptions, and each pattern family.

Do not wait until after DNS or routing changes to discover that the target environment interprets rule order differently.

Monitor outcomes after launch

Launch validation should repeat the critical pre-launch suite against production. Then monitor signals that can reveal missing or incorrect decisions:

• requests to legacy URLs;
• not-found and gone responses;
• unexpected redirect volume;
• crawl and indexing reports;
• important landing-page traffic;
• conversion paths that begin on migrated content;
• editorial reports of broken internal links.

Separate a missing redirect from a missing content decision. If requests repeatedly arrive for an unmapped path, determine what the audience expected before choosing a destination.

Set a review window and owner. Redirect maps should not become permanent piles of undocumented rules. Preserve redirects that protect durable paths, consolidate redundant logic, and document any removal criteria.

Connect the map to the migration release plan

The redirect map depends on the final content model, route design, content inventory, and cutover sequence. Changes to any of those inputs should trigger a review.

Use the Headless CMS Migration Checklist to connect redirect readiness with preview, editorial workflow, validation, rollback, and launch ownership. For the broader architecture behind the work, read Mastering the Headless Transition.

A strong redirect map makes every important legacy request accountable: where it came from, what should happen, why that outcome is appropriate, who approved it, and how the team proved it works.