• Publisert
  • 4 min

How to plan an EPiServer 7 upgrade or content migration – part 1

Making the jump to EPiServer 7 - Part 1: The concepts involved in an upgrade/migration.

See also:
Part 2: Mapping out your challenges

EPiServer 7 - upgrade or migrate?

One question keeps coming up from clients and fellow developers: 
“We’re moving to EPiServer 7 – should I upgrade or migrate from the old site?”

You’ll notice I conveniently left out “start from scratch” – as most new/relaunched sites reuse some code and/or content from the old site. 

Luckily, there are lots of ways to bring existing content into EPiServer 7, even from really old versions or from other CMS vendors. 

The best approach varies from project to project, depending on the site’s complexity and the client’s requirements. 

(That’s why you won’t find a standard price quote for this type of task.)

Let’s look at some of the concepts you’ll come across.

Definition of content

The default interpretation of content would be pages.

However, you often want to reuse more than just pages when moving to your new site. So in the context of upgrading/migrating, I’m liberally extending the definition to include:

  • pages
  • models (pagetypes/templates/composer blocks/tabs/categories etc)
  • users/roles
  • forms data
  • access rights
  • file archive

Essentially, everything that makes up your site, apart from the core framework.

What is an upgrade?

An upgrade is a scripted process to upgrade an EPiServer site to a newer version (either between minor versions like 6.0 to 6.2 – or major versions like 6 to 7). 

Note: The jump from EPiServer 4 to EPiServer 5 is technically considered a migration, since it requires a source site and a target site. Later EPiServer versions upgrade the source site directly.

To bring your site up to the latest version, you are often required to upgrade sequentially between one or more major versions (and sometimes a few minor versions as well). I’ve previously blogged about the upgrade process.

This is either done automatically via Deployment Center, or by running the upgrade scripts manually in the correct sequence. Unfortunately you can’t skip a major version when upgrading (e.g. 5 to 7 directly) because of breaking changes in data formats.

An upgrade performs the necessary transformations in your existing database and config files, allowing you to keep all your pages, users, access rights, forms data and file archive intact. 

You will, however, be required to modify your pagetypes, templates and plugins to comply with any breaking API changes or conflicting assembly dependencies between versions.


  • Automated scripted process using tool supported by EPiServer (Deployment Center)
  • Requires smaller code adjustments (fix breaking changes) rather than code from scratch
  • Preserves all of your pages, models (pagetypes/properties/tabs etc), forms data, user accounts and file archive


  • Unable to upgrade directly to newest version (must upgrade through all major versions in sequence)
  • Carries over obsolete content, abandoned users/roles and orphaned documents, which hog server resources and clutter the editor’s workspace
  • Carries over “technical debt” - deprecated API usage, outdated code standards and possibly non-upgradable custom plugins


What is a migration?

A migration is when you move/copy/export/mirror content from a “source site” to a separate “target site”.  The typical scenario is that you start with a clean EPiServer 7 project, then migrate in the parts you need from your old site.

In a migration, little is scripted. You are free to decide what content to migrate from the source, and how the target site consumes it.

You can use one of EPiServer’s built-in tools for this, use 3rd party tools or you can build custom tools that interact with EPiServer’s API or Web Services. Even copying editorial content by hand, property by property, is a kind of migration.

Migrations can be done between sites of the same EPiServer version, between sites on different versions, or from another CMS vendor into EPiServer.

While there are a few built-in tools for simple operations like export/import and mirroring, you often end up building custom tools that are intended for one-time use during migration.


  • Freedom to choose what parts to migrate
  • Save time by not having to upgrade the source site
  • Carries over less technical debt since only selected code is migrated
  • Good opportunity to make the client prioritize and prune the page tree
  • Existing content can be restructured into new formats (pagetypes/properties)
  • More future-proof since up-to-date API usage and code standards are applied from the start


  • Some built-in tools (import/mirroring) require that models (pagetypes/tabs/pagetree/ etc) is identical on both source and target site
  • Built-in tools can only migrate certain types of data
  • Customized databases/tables have to be manually migrated
  • A chunk of the project budget is spent on custom tools that will be discarded after migration

Mapping out your challenges

I should point out that not all upgrades/migrations are complex operations.

Sometimes you have a simple site that upgrades without problems to the newest version. Or perhaps your clean new site only needs a few old pages copy-pasted by hand.  

You may already have a good idea which approach is best for your site? 

For most sites however, there’s a number of challenges which require planning. Some of these are decisions which the developer will make, while others require input or action from the editor/site owner.


To be continued

In part 2, we’ll be looking at some of those typical challenges and how they dictate whether you should do an upgrade or a content migration.