Disclaimer: This website requires Please enable JavaScript in your browser settings for the best experience.

Dev GuideAPI ReferenceUser Guide
HomeDev GuideRecipesAPI Reference
Dev GuideAPI ReferenceUser GuideLegal TermsGitHubNuGetDev CommunityOptimizely AcademySubmit a ticketLog In
Dev Guide
Legal TermsGitHubNuGetDev CommunityOptimizely AcademySubmit a ticket

Upgrade from legacy versions

This topic describes how to upgrade from versions of Optimizely Content Management System (CMS) prior to CMS 7.

Suggest Edits

To upgrade Optimizely Content Management System (CMS), you need to upgrade from one major version to the next, step by step. This page gathers the relevant links needed to do so, if you are on the earlier versions 4, 5, or 6. From version 7, see the Upgrade CMS sections.

This link collection was put together by Arild Henrichsen.

Upgrade from CMS 4 to CMS 5

If your existing site is pre-4.62:

If your existing site is 4.62:

See the following documentation:

Migrating from CMS 4.62 to CMS 5 R1

1. Download and install .NET 3.5 SP1

2. Download and install CMS 5 R2

3. Obtain a valid CMS 5 license

4. Prepare existing 4.62 site (source):

  • Back up existing site and database.
  • Verify that database connection string is correct.
  • Verify that paths to filesystem (upload) and admin/edit UI are correct.
  • Verify that the site is browseable, login works and it has a valid license.

5. Install a new CMS 5 R2 site (target) using CMS Manager:

  • Must use new database, but a pre-existing database user account can be used.
  • Supply a valid license.
  • Do not install Public/Demo Templates.
  • Verify that NETWORK SERVICE and IUSR_ accounts have read/write access to the web site root.
  • Verify that the site is browseable.

📘

Note

If using IIS 5 (e.g. WinXP), only one site may be running at a time. In this case, stop the old 4.62 site and start the new CMS 5 R2 site before continuing.

6. Install and run the Migration Tool 1.1.0.38:

7. Copy the files from the 4.62 site over to the CMS 5 R2:

  • Templates folder, language files, scripts folders, any plugins or custom properties folders.
  • Filesystem (upload) will be converted and copied automatically during the migration.
  • Merge differences between the 4.62 site web.config and the CMS 5 R2 site web.config (applicationSettings, upload path, UI path and so on).

8. Handle breaking changes:

9. Test CMS 5 R2 site:

  • Verify that site is browseable and that admin/edit login works.
  • Verify that the filesystem is intact.

Additional references for CMS 4/5:

Challenges when moving from CMS 4 to CMS 5:

Rewrite code to handle breaking changes:

Rewrite from ContentFramework to ASP.NET 2.0 MasterPages:

Replace EPiFields with Dynamic Content:

Handle changes in the configuration files:

Implement the ASP.NET 2.0 Membership/Role Provider system:

Changes to the filesystem:

Troubleshoot - CMS 4 to 5

_Errors during EPiServer 4 installation/configuration:

ERROR: Cannot install files: The installation failed, and the rollback has been performed. [The name is already in use as either a service name or a service display name]
CAUSE: A newer version of the EPiServer Scheduler service is already installed on the web server. Installing EPiServer 5.x on a system where EPiServer 4.x is installed is OK, but the other way around causes problems. 
SOLUTION: Go to Administrative Tools > Services > Stop and disable the "EPiServer Scheduler service".
OPTIONAL SOLUTION: 

  • Control Panel > Add/Remove Programs > Uninstall the EPiServer CMS 5 Scheduler service.
  • Reinstall EPiServer 4.x and EPiServer 4 Shared Components.
  • Run migration, then reinstall EPiServer 5.x and EPiServer 5 Shared Components.

For more information see:
Problems installing EPiServer 4.x with newer versions of EPiServer and .NET present

ERROR: 
System.Web.Services.Protocols.SoapException: Server was unable to process request. ---> System.NullReferenceException: Object reference not set to an instance of an object.

  at LicenseRegistry.LicenseCreator.CreateLicense(License license)   at LicenseRegistry.DataAbstraction.License.CreateLicenseFile()
at ProductUpdate.InstallUnit..ctor(Int32 licenseNumber, String licensedCompany) in C:\LicenseRegistry\Production\ProductUpdate\InstallUnit.cs:line 30
at ProductUpdate.UpdateManager.AddLicense(Product prod, InstallUnit[] units) in C:\LicenseRegistry\Production\ProductUpdate\UpdateManager.asmx.cs:line 132
at ProductUpdate.UpdateManager.RequestInstall(Product product) in C:\LicenseRegistry\Production\ProductUpdate\UpdateManager.asmx.cs:line 122

CAUSE: When installing EPiServer 4.62B using online package, there is a known problem with the licensing system (seems the installer tries to generate/validate a license even though a license file has been supplied).
SOLUTION: Use EPiServer Manager to create an offline installation package, and install from that instead (still using EPiServer Manager).

ERROR: System.Security.Cryptography.CryptographicException: Bad Data
CAUSE: Web.config is encrypted, containing lines with values that could not be decrypted (was encrypted on another server - encryption is partly based on unique machine keys).
SOLUTION: Replace the values in lines containing "ENCRYPTED" with plain-text values (can be found using EPiServer Manager on the server where the web.config was originally encypted, or insert values matching the new server).

Errors during migration from 4.x:

ERROR: Failed to register ASP.NET client scripts on this site [The system cannot find the file specified]
Cause: Migration Tool is dependent on .NET 2.0 and is conflicted because .NET 3.0 or higher is installed on the system. 
Solution: Temporarily move or rename the following folders:

  • C:\WINDOWS\Microsoft.NET\Framework\v3.0
  • C:\WINDOWS\Microsoft.NET\Framework\v3.5
    then retry the Migration Tool.

ERROR: Cannot find Stored Procedure "dbo.aspnet_CheckSchemaVersion":
SOLUTION: Perform the following steps:

  • Locate C:\\WINDOWS\Microsoft.NET\Framework\v2.0.50727\aspnet_regsql.exe.
  • Use the 4.62 database as command line argument and run with default settings.
  • Restart SQL Server.
  • dbo.aspnet_CheckSchemaVersion should now be found in the database.

Move from CMS 5 to CMS 6 R1

See the following documentation:

1. Download and install CMS 6 R1

2. Obtain a valid CMS 6 license

3. Upgrade the existing CMS 5 site using the Deployment Center:

  1. Deployment Center > EPiServer CMS > Version 6.0.530.0 > Upgrade Site with SQL Server database.
  2. From the list, select the CMS 5 site you want to upgrade
  3. Click Upgrade to start the process
  4. On completion, close the Deployment Center.

4. Install new CMS 6 license

5. Test the new CMS 6 site:

  • Verify that the site is browseable and that admin/edit login works.
  • Verify that file system is intact.

Challenges when moving from CMS 5 to CMS 6:

Handle breaking changes:

Web.config being split into multiple configuration files:

XForms being converted to the new Dynamic Data Store:

Path to admin/edit view changed because of Online Center:

Additional references for CMS 5 / 6:

Upgrade from CMS 5 R2 to CMS 6 RC1:

Move from CMS 6 R1 to 6 R2

See the following documentation:

1. Download and install CMS 6 R2

  • Download Episerver CMS 6 R2
  • Always download the installer directly from Episerver World, to ensure you have the very latest version (with all the patches and bugfixes included).

2. Obtain a valid CMS 6 R2 license

3. Upgrade the existing CMS 6 R1 site using Deployment Center:

  1. Deployment Center > EPiServer CMS > Version 6.1.379.0 > Upgrade Site with SQL Server database.
  2. From the list, select the CMS 6 R1 site you want to upgrade.
  3. Click Upgrade to start the process.
  4. On completion, close Deployment Center.

4. Install new CMS 6 license

5. Test the new CMS 6 site:

  • Verify that the site is browseable and that admin/edit login works.
  • Verify that file system is intact.

Troubleshoot - CMS 6 R1 to 6 R2

Upgrade Xforms fails:

Blank page references in "Fetch-data" function:

Upgrade CMS 6 R1 sites that run .NET 4:

Issues when upgrading to CMS 6 R2:

IE11 incompatibility issues patch:

Updated 3 months ago