How to Plan a Content Management System Migration

October 29, 2019
How to Plan a CMS Migration blog image

Walking through the steps to migrate from one Content Management System (CMS) to another can take you down many roads. Every migration is different. We took a step back to look at some commonalities and provide a high-level guide to planning a CMS migration. While this is not intended to be exhaustive, it will give you a structure for making sure the right conversations are happening when you need them.

Let’s get started! Each section is intended to be a sequential step in the process. However, throughout the migration, it is expected to revisit the activities of previous steps as new information is uncovered.

Audit the Existing Content

First, audit the existing content to understand what needs to be migrated. If you’re migrating from multiple CMSs to a single CMS this will be a significant undertaking. But, this information sets us up to make cost-effective and goal-oriented decisions later as we build our migration plan. And, this allows the team to see all the content in a centralized place, maybe even for the first time!

We provided tips before in 3 Keys To Auditing Or Migrating Any Website for auditing your site for a migration. Let’s focus here on doing a website crawl using Screaming Frog, which can be configured to access content behind authentication if needed. This will help us survey how much content is publicly available on the site.

Put the full list of URLs into a spreadsheet; see our Free Excel Workbook For Analyzing Screaming Frog Data for an example. Scan through to take particular note of certain content types — this activity is best done by the person who is also coming up with the data model for the new CMS. For example, if you see a lot of URLs at /blog/{title}, then pencil in that you need a content type that supports blog content. If you see a lot of URLs at /about/staff/{name}, then note you need to support staff content. Your summary table may look something like:

Content Type Count URL Pattern
Blog 983 /blog/{title}
Staff Profile 56 /about/staff/{name}
Event 731 /events/{name}
Basic Page 1,258 NA
PDF 123 /documentst/{name}
Image 2,014 /images/{name}

Now, we know we have roughly four content types with about 3,000 pages and 2,100 assets total that are crawlable on the site. There might be more content in the CMS. If you have access to the IT team involved in the original CMS, you can request a spreadsheet export. Or, perhaps the CMS gives you a way to do this yourself, or at least browse around to see how much content might be missing from this audit.

Once you’ve created a list of all content organized by group, you can evaluate the options for migrating.

Plan the Migration Workflow

Not all content will go through the same workflow to get from the old CMS to the new CMS. Don’t immediately jump to the conclusion that you should send all your content through a programmatic migration workflow. There are at least three paths for moving your existing content, and each can be used in combination with others.

Option 1: Drop Pages or Consolidate Them 

Websites, just like organizations, evolve and change over time. This leaves the opportunity for content to have been created that served a purpose in its time but is no longer relevant. Or, it is deprecated by new content. This is an opportunity to drop some of those pages that have low conversions or low traffic and redirect them to a consolidated page.

Option 2: Manually Re-Author Content

After looking at the amount of content and its complexity, you may conclude it will be cheaper to manually re-author content instead of programmatically migrating it. It‘s also an opportunity for you or your staff to get familiar with the authoring experience of the new CMS before you’re fully transitioned into it. 

Option 3: Programmatic Migration of Content

Programmatically migrating content is a great fit for large quantities of similar content. For example, a blog post section with a thousand pages that follow a similar format of “headline-byline-content” is a good candidate.

Design the Right Workflow for Your Migration

In What Should You Do With Old Content? we expand on these options and give some guidance on how to make such a decision for your content. For expediency, we won’t dig into that reasoning here and instead, we’ll use our example from earlier and say we want to programmatically migrate Blog, Event, PDF, and Image content types and the rest will be manually re-authored or consolidated. This means you’ll need to prepare content authors for creating almost 1,300 pages! Unless, of course, you apply a strategy to consolidate low performing pages.

Once the content is in the new CMS, you’ll likely have additional checks and changes to make. There will be SEO review, accessibility review, verifying redirects are in place, making sure any functionality on the page still works (e.g. share buttons), or verifying the content matches the desired brand and voice. You also may have governance checks to make sure the right people are approving it before it’s published.

The diagram below might help you conceptualize what such a workflow might look like:

example of possible content migration workflow diagram

For further reference, Content Strategy is All Around Your Project will help you design the right workflow for your migration.

Design Your Content Model

Start with the end in mind. Now that you’ve got familiarity with the data in sufficient granularity to identify content types, take it to the next level to identify the field-level detail for those content types. You’ll need to use knowledge of how content was structured in the old CMS as well as the capabilities the new CMS has for structuring content.

This is the most rigorous step. Getting this wrong may mean significant rework later as you need to change all the migrated content. Getting it right means the execution of your migration plan will be efficient. 

To help you organize your content model, you may use a content matrix or spec tool in a spreadsheet. You can look at the Acquia Drupal Spec Tool for an example. Again, good content strategy and information architecture is going to help, and in this case, it will help structure your content in a way that promotes engagement and re-use across mediums.

Map the Data

Now, you know where you’re going. How do you get there? There are two concurrent paths your project team will take: one for the programmatically migrated content and another for the manually re-authored content. In both cases, we will take the field-level detail from our Content Model and identify how the content from the old CMS maps to it.

Mapping Programmatically Migrated Content

For programmatically migrated content, it won’t be enough to have the field-level detail of your new CMS content model. You’ll need field-level detail of the old CMS content model as well for any content you are programmatically migrating. With this information, you can make a field-to-field mapping between the two systems. This mapping should include notes about the format of the data being migrated, for example, is it a CSV? It should include what transformations need to be applied to the data as it’s migrated to the new CMS. It’s at this step that you’ll want to choose an Extract-Transform-Load (ETL) tool to help with running the migration.

As you build the mapping, you’ll start to find cases where the data model might need to change to support the migration. Having expertise in both the old and new CMS will certainly come into play here as you’ll more quickly understand what changes to make.

Mapping Manually Re-Authored Content

For content that is manually re-authored, you won’t need the same type of detail. Instead, you’ll need guidelines and training for the team that is writing the content so they know how to take a page from the old CMS and build it in the new one. This will vary based on the CMS you’re migrating into.

Generally, your guidelines and training should include things like how to create the page based on the type of content (you might need to navigate to different areas of the CMS to create a given page), how to ensure the URL is correct, that it shows in the correct navigations, what meta-information to set, and how to add contents that are “components” on the page. Having a component library with explanations of the purpose of each and how to use them will help enable your content authors to build the pages correctly.

Execute the Migration

With the mapping from the source to destination CMS, you’re ready to execute the plan! The migration workflow should help your team understand what can be done in parallel versus what should be done in sequence. For example, perhaps you programmatically migrate all assets before manual content entry starts so that images are available from the start.

Throughout the migration process, make sure all related parties are meeting frequently to surface issues. It may be a good idea to go through a small portion of the content and migrate it to see if there are any problem areas that require changing the process or methods.

Common Challenges

There are some easy mistakes to make as well as some known caveats to writing a migration from one CMS to another that are important to note here. Knowing these can help you navigate a more successful migration with your team.

Lift and Shift

It may be intuitive to assume the least costly migration is a “lift and shift,” where you take all the existing functionality and design and rebuild it the exact same way on the new CMS. You might be thinking this avoids additional costs of redesign, strategy, and re-defining or re-thinking requirements. This way of thinking will lead you to a major pitfall.

A “lift and shift” isn’t a shortcut, it’s the long way around and will cost significantly more than having a good strategy for your migration. Typically, your old CMS has one-off functionality and technical debt that are cheaper to consolidate or build new than migrating as-is. Yes, a CMS migration is a major undertaking, but now is the right time to focus on content strategy, a limited redesign that at the very least consolidates superficial or low-value content variations, and evaluating Return On Investment (ROI) of functionality that will be customizations in the new CMS.

Invalid Data

You will have invalid data. No two CMS think about data in exactly the same way, which means you’re most likely going to have migrated data that is invalid. You can mitigate this by having good checks in your workflow. For manually re-authored content this could mean putting all the content in a spreadsheet or using a tool like Gather Content to help surface issues early. For programmatically migrated content, you can implement some automated checks within the ETL tooling, for example, skipping certain data that is missing a required field.

What do you do with that one piece of content that’s missing a required value? Do you skip migrating it altogether or is there a reasonable default you can use? The more fields you can identify an acceptable default value for in the event of missing or invalid data, the higher the rate will be of successfully migrated content. This principle doesn’t just apply to programmatically migrated content; your content authoring guide can include recommended default values as well.

Don't skimp on the non-visible fields in your CMS that provide contextual relevance, like categories, and contribute to the page's meaning, like on-site schema and page-level metadata.

Expediting Review For Quality

There are a lot of steps involved to make a migration successful. Each one poses an opportunity for a lot of errors that can cause rework and delays on your project. While it can be tedious, good quality assurance (QA) checks are critical. They ensure you are addressing issues at opportune moments rather than waiting for them to surface on launch day.

Ensure you are planning enough time for it. There are ways to improve the likelihood you find truly business-impacting issues:

  • Focus QA efforts on the highest SEO performing content.
  • Find ways to programmatically verify the migrated content — remember how we used Screaming Frog in the beginning to crawl for content? Run the crawler on that same list of URLs to make sure they all redirect properly, perhaps also exporting metadata like the page title for comparison between new and old.
  • Use tools to audit for SEO or Americans with Disabilities Act (ADA) issues and compare before and after the migration.

Expecting Improvements to Migrated Content

The classic phrase “garbage in, garbage out” applies to migrated content. If your previous content had ADA issues or low performing SEO, then set accessibility goals and SEO goals in the migration workflow. If you have low engagement with your user base or they find the site confusing, plan to include content strategy efforts in your CMS migration. If part of the project’s objective is to improve qualitative aspects of your content, you must plan for it.


You should now understand the high-level steps for planning a CMS migration:

  1. Audit the existing content.
  2. Plan the migration workflow.
  3. Design your content model.
  4. Map the data.
  5. Execute the migration.

And, we discussed some common mistakes to avoid along the way. Success takes many forms and is contextual to your project, but they all point towards building a more relevant and engaging Internet. We hope this guide helps you to achieve the same with your migration