The Not So Complicated World of Web Content Migration – Part 2:The Avalon Way


In the post Web Content Migration – Part 1, we discussed the context behind content migration, the high level details as well as some of the important tasks and facts that needs to be considered before starting the migration. In the second part of the blog, we break the migration tasks into simple, relevant and concrete steps that could be followed and implemented by any project team.

Initial Discovery and Findings

Before getting into the actual migration, one of Avalon’s standard and recommended practices is to run an initial discovery phase. The objective of this exercise is to gain an initial understanding of the actual implementation of the current and proposed systems. The following activities occur during this phase by meeting with the business, technical and content management teams:

  • Review the current CMS implementation.
  • Understand the scope of migration and timelines.
  • Understand the newly proposed design, current business processes, and issues and concerns with the current setup and process.
  • Review the proposed CMS implementation.

The output of this phase is a findings report called the ‘Content Plan’ which contains the following details pertaining to both the current and the proposed system:

  • A rough estimate of the number of content instances that need to be migrated broken into different categories such as templates, text, audio, video, documents etc.
  • Details regarding Content Type Definitions (CTD) or Schemas.
  • Project / Folder organization as well as site specific organization if any.
  • Navigation structure
  • Client specific customizations implemented in the current CMS some of which may or may not be part of the migration.
  • Users, groups and their capabilities (what and where) within the CMS as well as user authentication process
  • Workflows, content validation and taxonomy and classification
  • Delivery channels such as Mobile, Tablet, and Web etc.
  • Test content
  • Content that could retired and left behind.
  • Content & Controls specific to various aspects such as display, personalization, translation, decision engine etc.

The Content Plan document containing the findings and recommendations is shared, reviewed and updated with the client. Once it is accepted and approved by the client, the next step is the actual content migration process.


Content Migration Overview

The migration process consists of the following steps:

  1. Install the new CMS environments
  2. Document the current state of content in the existing CMS.
  3. Document the proposed state of content in the new CMS.
  4. Create mapping specifications between the current and proposed systems.
  5. Create scripts/programs to perform migration based on the mapping specifications
  6. Create test plan and test cases/test scripts.
  7. Perform migration to the new CMS in the test environment.
  8. Perform migration validation and verification in the Test environment.
  9. Clean up content versions in the existing CMS production environment.
  10. Freeze content in the old CMS Production environment.
  11. Perform migration to the new CMS in the Production environment.
  12. Review and validate the migration in Production.
  13. Perform a delta migration of content created or modified after the main migration.

The Milestones diagram below illustrates the sequence of events in a content migration.

Migration Milestones

Content Migration: Detailed Process Steps

Step1: Complete Installation of New CMS

Before the migration can begin the new CMS needs to be set up and running in at least two environments: Test and Production.  Environment setup should include administering at least a subset of users in different roles to support migration validation.  A preliminary version of the website content should be available to test how content renders after migration.


Step2: Document the Current State of Content

A more detailed documentation is carried at this stage.  The full documentation of the current state includes:

  1. Design of Content Type Definitions (CTD) or Schemas, including customizations.
  2. An updated count of Content Instances by CTD or Schema
  3. Static Files
  4. Navigation Structure
  5. Project/Folder Structure
  6. Users/Groups/Capabilities
  7. Workflow Definitions
  8. Classifications or other tagging of content
  9. URL Redirects
  10. Presentation Templates
  11. Permissions on content instances, static files, projects and channels.
  12. Content to be left behind, including projects, content instances, Content Type Definition, and channels.  We recommend moving all unneeded     content objects to a separate location in the current CMS before starting the migration.
  13. The relationship between different content instances and static files needs to be documented. For example, a content instance may rely on a static file being in a particular location on the files system.  That relationship will need to be maintained in the new system.
  14. Client specific CMS customizations


Step3: Document the Proposed State of Content in the new CMS

The structure and design of the new CMS needs to be completed and documented before the migration can begin.  The documentation of the proposed state includes:

  •  Design of new content type definitions or schemas.
  •  Location of static files
  •  Navigation structure
  •  Content organization structure
  •  User access control
  •  Other CMS specific-settings and handling of customizations


Step:4 Create Content Mapping Specifications

Once the new system and its requirements are finalized, the mapping between old and new system can begin.  Rules for mapping each content instance will need to include multiple attributes about that content, as show in the following diagram.
Overall Migration Details

Mapping Scenarios

 As part of migrating content and creating new content in the new CMS there are at least four use cases or scenarios which we need to consider:


Scenario 1: Old to New 1:1

Scenario 1: Old to New

Scenario 2: Content Break-up One: Many

Scenario 2: One to Many

Scenario 3: Content Left Behind (Retired or Out of scope)

Scenario 3: Retired or Out of Scope

Scenario 4: Brand New content (does not exist in the current or Old CMS)

Scenario 4:  Brand New Content


Some additional considerations for mapping and migrating content include:

  • Identifying and verifying content and related content objects that will be left behind.
  • Identifying content that is used to hold a site together, which we call “lynchpin content.” The site may rely on content to render pages and will need to be reproduced in the new CMS.
  • Identifying new content that is not part of existing system but needs to be added to the new system in conjunction with migrated content, e.g., new fields in the new CTDs or Schemas
  • Reproducing customizations in the new CMS and understanding how to apply them selectively to migrated content
  • Reproducing the security setting and applying them to migrated content, content organization, and navigation


Step:5 Create Migration Scripts/Programs

After the migration specification is created, validated and approved by both the business and technical teams, the script or program needed to perform the migration needs to be created, validated and tested in the development environment. This task consists of the following:

Extract Content from Source CMS

  • Extract content from CMS
  • Test and verify the accuracy of the extraction and make appropriate changes to the script or program if needed.

Import Content to Target CMS

  • Create scripts/programs to perform migration based on mapping specs
  • Run migration script to import data to the new CMS
  • Test and verify the accuracy of the import and make appropriate changes to the script/program if needed.


Step:6 Create a Test Plan and Test Scripts

After the mapping is complete and before the migration is run, you will need a test plan to validate that the migration is working as expected and to verify that all the content has been migrated correctly.

The initial validation tests one or two of each kind of content to ensure that mapping works correctly.  Migration verification testing involves developing and running reports that will show whether all of the content made it through the migration.  If any content failed to migrate, the reports should highlight which instances are problems or may need to be recreated manually in the new CMS.


Step:7 Perform Migration to the New Test Environment

Once the migration script, test plan and test scripts are validated and approved, the migration process is run on a test environment using an export from the old CMS. The migration is from content exported from the old CMS in Production environment to the new CMS in the Test Environment.


Step:8 Perform Migration Validation and Verification in the Test Environment

Two sets of validation need to be performed during this step in the migration:

a) Verify if content has been migrated to the appropriate location in the target CMS.

There are different kinds of errors that can show up during this process:

  • Content Issues – Content can be missing, placed in the wrong location, or have incorrect attributes.
  • Mapping Specifications – The mapping specification may be incorrect or incomplete.
  • Script Failures – The script may not run completely or correctly and needs to be corrected.
  • CMS Configuration – The migration may fail because the new CMS has not been configured correctly.

These errors can be related to each other. Corrections to the script and mapping specifications will often need to be made together.  The migration may need to be run and tested more than once to ensure a complete test.

b) Verify that both the migrated content and new manually-entered content work together to render pages correctly on the website(s).


Step:9 Clean Up Content Versions in Production

The migration will move only the last version of each content instance.  If there is content that is being versioned and edited, content managers will need to track what changes are in progress during the migration.


Step:10 Freeze Content in Production

After the bulk of the content has been migrated and the migration has been tested, content changes in the old CMS needs to be frozen.  The content freeze should be enforced by removing access or at least update privileges.  The content freeze should also be applied to the new CMS in the production environment while the delta content is being imported.


Step:11 Perform Migration from Old to New in Production

Perform migration in the Production environment by running the validated version of the migration scripts/programs.  Since content will have changed since testing, the production migration begins with a new export from the old CMS.


Step:12 Validate the Production Migration

Repeat verification and validation steps conducted during the test migration.  The emphasis in the production migration will shift from ensuring that the migration works correctly to validating that all content has been migrated.


Step:13 Delta Migration & Validation

A final export from the old CMS will pick up all content that has been created or modified since the main migration and import it to the new CMS in production.  As soon as the content has been imported and published, a final validation should be run to make sure that the websites are rending content correctly.



The steps mentioned above will apply to any content migration but how they are executed depends on the features of the old and new CMS. It also would depend on the depth of the customization carried out by the client as well as various other features implemented such as analytics, segmentation, etc.

Avalon has delivered successful content migrations for many of our clients and we can apply this process for you too.  By following the steps and adapting  them to your specific CMS platform and business needs, we can make your content migration a  success.


UPDATED TO ADD:  consider reading my colleague Will Thayer’s post specific to migrating to a *new* CMS, Migrating content to a new Web Content Management System.

Felix Simon is a Senior Consultant with Avalon Consulting, LLC

Felix Simon About Felix Simon

Leave a Comment