EPiServer CMS Migration Tool 1.1

Introduction

This technical note contains functional and technical information for the migration tool that is used to migrate EPiServer CMS sites from EPiServer CMS 4.62 to EPiServer CMS 5 R2.

The EPiServer CMS 4.62 database is migrated in place and receives all the necessary configuration on the target CMS 5 site. After migration, the CMS 4.62 database has been converted to the CMS 5 schema, the CMS 5 site has configuration settings that map to the CMS 4.62 configuration, and its connection string points to the converted CMS 4.62 database.

Table of Contents

• Preparing for Migration
• User Handling
• Register Custom Event Handlers
• Language ID Conversion
• Execution Order
  » Migrate Object Store Data in the Database
  » Migrate Other Data in the Database
  » Migrate Enterprise Sites
  » Migrate Unified File Systems
  » Change LongString Properties to XhtmlString
  » Migrate Links
  » Migrate Page Types
• What Happens After Migration?
• Troubleshooting
• EPiServer 4.62 Assemblies with Version Numbers

Preparing for Migration

There are certain steps that must be carried out before you can migrate your site to EPiServer CMS 5 R2. These are described below.

• Microsoft SQL Server Database.
  If your EPiServer CMS is configured with a Microsoft SQL 2000 database, update to Microsoft SQL 2005 first, before using the migration tool. 
   
• Oracle Database Server.
  You must set up all the prerequisites for EPiServer CMS 5 R2 on Oracle. Set the connection String Attributes within the web.config CMS 4.62 to Enlist = "false" to ensure that connection is not context-specific.
     <appSettings>
          <add key="EPsConnection" value="User Id= EPISERVER;Password= EPISERVER;Data Source= EPISERVERORACLE;enlist=false "/>
  After migration this should be removed from ConnectionString.config and web.config.
     
• Back up the CMS 4.62 database.
  It is recommended that you run the migration on a backup of the database. Check that there is no other traffic towards the site/database during migration. NOTE - The migration process is very database intensive. Increase the performance of the migration process by setting the "Recovery model" for the database to SIMPLE during migration.
    
• If necessary, upgrade the EPiServer CMS site to be migrated to 4.62 using EPiServer CMS Manager.
  EPiServer CMS 4.62 is the only supported version for migrating to EPiServer CMS 5.
   
• Install an unmodified EPiServer CMS 5 R2 site on same machine as the 4.62 site.
  Use EPiServer CMS Installer to install the EPIServer CMS 5 R2 site.
   
• Install the migration tool on the same machine as the sites.
   
• Ensure that the EPiServer 4.62 assemblies are already installed on the EPiServer CMS 5 R2 site machine - in the GAC (Global Assembly Cache).  Copy the assemblies to the CMS 5 site machine if they do not exist there. The EPiServer 4.62 assemblies and their versions are listed at the bottom of this tech note.
   
• Remove any custom tables added in the database with constraints towards any EPiServer CMS tables.
  For example, if there is a custom table that has a foreign key that is a column in an EPiServer CMS table. The reason for this is that during migration the existing EPiServer CMS tables will be dropped, which requires that no other tables have constraints towards the tables.
   
• Remove or convert any Form properties to XForm properties.
  Check whether any Form properties need to be managed by starting the migration tool, select the different web.config files and click Next. The migration tool checks for any Form properties and displays a message indicating which properties need to be managed before migration. 
   
• Exclude any file systems that you don't want to migrate.
  The migration tool will migrate all native file systems to versioning file systems. If there are any file systems (or part of a file system) that you don't want to migrate, make sure the configuration excludes that before migration. See Migrate Unified File Systems. 
   
• Separate page folders.
  If you have all your uploaded content in one folder it is recommended that before you begin to migrate that you separate the page folders from the upload folder.
  
  If you want your page files from 4.62 to be in a separate folder you could take all folders named as a number (those are your page files) in your upload folder and move them to another folder and name that folder "Page Files". Then you add another handler in web.config so it looks something like the configuration below (change the physical path to a valid one):
  <handler pagedirectory="False" virtualname="upload" virtualshare="True" type="EPiServer.FileSystem.Handler.NativeFileSystem,EPiServer">
      <customsettings physicalpath="c:\Upload\Public\upload" />
     </handler>
     <handler pagedirectory="True" virtualname="Pages" virtualshare="True" type="EPiServer.FileSystem.Handler.NativeFileSystem,EPiServer">
      <customsettings physicalpath="c:\Upload\Public\pages" />
 </handler>
  You will also have to add mappings for the folders:
  <mappings>
     <map fromPath="/upload" toPath="/pages" type="EPiServer.FileSystem.Mapping.PageDirectoryMapping,EPiServer" />
 </mappings>
  Documentation explaining how to use PageDirectoryMapping to separate page folders from the upload folder is available in the Unified File System technical note - see the section entitled Move Folders Around / Mappings. 
• Update Blog Templates.The blog templates for CMS 4 uses Xforms to store blog posts and comments. When migrating a problem occurs regarding comments - due to the fact that the comment does not get a page id set (defaulting to 0) when created. This causes the migration tool to ignore the comments.
  The migration log will show:
  Page with id 0 does not exist, hence dropping XFormData for that page.
  
  In order to circumnavigate this problem - download and run the comment fix script before migrating - this sets a page id for all comments.
    

Recommendation:
To minimize the risk of encountering problems whilist migratiing EPiServer CMS 4.62 to EPiServer CMS 5 R2, it is our recommendation that the migration tool and the SQL Server exist on the same machine whilst migration is being performed. If this is not a possibility and you encounter problems during migration see the troubleshooting section or even the migration tool FAQ.

User Handling

In EPiServer CMS 4, users were identified using a SID (int based). In the ASP.NET membership model used in EPiServer CMS 5, a user is identified by his/her username. During migration all references to users/roles (e.g. regarding access rights) are migrated from a SID reference to a username reference, meaning all access rights will be kept by migration.

It is optional if users, roles and personalized data stored in EPiServer database should be migrated. The way migration of users/roles works is that the migration tool will read the users/roles from the 4.62 SID tables in the database and then use configured membership/role providers to create the users/roles. During this step the migration tool will create new random passwords for the users. The generated users including password and email will be stored in a csv file (a file migratedUsers_<bdName>.csv is generated in the Migration tool folder) so the site owner can administer the users after migration. The format of the file is one user per line and each line is on format <username>, <password>, <email>.

It is also possible to configure if migrated windows usernames should be stored with domain prefix or not (even though windows users are not migrated they can occur e.g. in access tables). In EPiServer CMS 5 it is possible to configure which format of username the user should have e.g. username or domain\username. So the selection during migration should be affected by how you plan to configure your CMS 5 site.

NOTE: Migration tool will not change the provider configuration on the target CMS 5 site, so after migration you might want to change the configuration from default Windows providers to SqlServer or Multiplexing providers. 

Register Custom Event Handlers

The migration tool exposes a lot of extension points, which makes it possible to register external event handlers that will be called during migration. To register an external event handler, add an entry under the extensions configuration element in the App.config file for the migration tool.

Example:

The classes specified as extension modules must implement the EPiServer.Migration.IMigrationExtension interface, which is specified in the EPiServer.MigrationEngine.dll assembly.

At startup the migration tool calls the Initialize method for all extension modules. Each extension module will then register event handlers for those extension points in the MigrationContext.Events class that the module wants to act upon.

Language ID Conversion

In EPiServer CMS 4 it was possible to define language codes for languages. In EPiServer CMS 5 each language code must be parseable as a .NET CultureInfo object. During migration, the migration tool parses each language and if a language code is not parseable as a CultureInfo object, a dialog will be displayed, where language mappings can be performed. (Each language code marked with '*' must be changed). An example is the language code for Danish, which in some previous versions was stored as 'DK', but in CMS 5 should be 'DA'.  

Execution Order

The migration tool uses a workflow, based on Windows Workflow Foundation, as the execution engine. The order in which different parts of the migration takes place is explained below. Some of the steps are explained in more detail below.

1. Migrate users/role.
2. Migrate old Personalization Info (profiling)
3. Migrate object store data in the database.
4. Migrate other data in the database.
5. Update database schema to CMS 5 R2.
6. Update the web.config file on the target site:
   • according to the setting in the 4.62 site.
   • with any enterprise settings.
7. Register the ASP.NET sql files in database.
8. Register workflow (WF) scripts in database.
9. Migrate unified file systems.
10. Change LongString properties to XhtmlString.
11. Migrate links.
12. Migrate page types.
13. Update EPiServer.IndexingService with new file systems that should be indexed.

If the migration is canceled (by clicking Cancel), the migration will stop as soon as it reaches a checkpoint. The next time migration is started, you will be asked if you want to start from where the previous migration was canceled. It will then start executing the same step from the beginning of that step, with the exception of file and link migration, which will continue from where it was at cancellation.

Migrate users/roles

Through UI it will be possible to configure which of users,roles and personalized data to migrate. It is also possible to specify which Membership/Role/Profile providers to use during migration in the config file (typically C:\Program Files\EPiServer\MigrationTool\MigrationTool.exe.config). Default it will use the SqlMembership/SqlProfile providers to store the users/roles/Profile in the aspnet tables. Here it is also possible to configure the providers such as passwordFormat etc. It is also possible to implement event handlers for EPiServer.Migration.UserAndGroupHandler.MigratingUser and EPiServer.Migration.UserAndGroupHandler.MigratingRole events. Through the event handlers it would be possible to e.g. change generated passwords, add missing emails etc. See event section above about how to register event handler. 

After the migration the external users will not be able to login by default since the passwords are randomly generated. One option is to use the generated file migratedUsers_<dbName>.csv to send out the generated passwords to the users. Then the site could have a page with a ChangePassword control available so the users can administer the passwords themselves. Another option is to have a page with PasswordRecovery control so the users can get an email with a new password (it might be useful to have a ChangePassword control in this case also so the user can choose their own password), this will though require that the user has a valid email address given. 

Another option could be to not migrate users when running Migration tool, but instead use the membership provider provided on labs.episerver.com. in that case users are migrated "on the fly" as they login. You should though be aware of that it is an experimental project that has not been tested extensively so the usage of it is unsupported.

Specific for Oracle

By default  MigrationTool.exe.config  is set up to run on SQL Server. When running on oracle comment and uncomment the lines specified.

It is also required to run the Oracle Providers for ASP.NET(ODAC 11g) scripts in Oracle with the user EPISERVER 4.62, which is going to be migrated to EPISERVER CMS5 R2. You'll find the scripts underneath the installation folder of ODAC 11g(@<ORACLE HOME>\product\11.1.0\client_1\ASP.NET\InstallAllOracleASPNETProviders.sql) as it is done for Episerver CMS5 R2.

Migrate old Personalization Info (profiling)

Through UI it will be possible to configure if the old personalized data will be migrated to the new model of profiling provider. It is also possible to specify which Profile provider should be used during migration in the config file (typically C:\Program Files\EPiServer\MigrationTool\MigrationTool.exe.config). Default it will use the sqlprofile provider to store the Profile in the aspnet tables. It is also possible to implement event handlers for EPiServer.Migration.MigrateUserProperty.MigratingUserProperty event. Through the event handler it would be possible to e.g. change the propertyValue and have control over the ProfileBase object etc. See event section above about how to register event handler. 

After the migration the old personalization info will be a part of the new profiling model.

Migrate Object Store Data in the Database

The migration tool handles all EPiServer CMS-specific objects persisted in the database, except objects with schema name WsrpPortalInfo, WsrpPortalPageSession. These objects are not supported by EPiServer CMS 5.

Migration Of Custom ObjectStore Items

Any custom objects stored in EPiServer ObjectStore will not be automatically migrated with the migration tool. However, the migration tool provides an extension point where it is possible to plug in and add your own module that will handle migration of your custom object types.

This example provides a short explanation of how the plug-in should be done.

1. Create a new class library project and add references to :
   • EPiServer.BaseLibrary
   • EPiServer.Implementation
   • EPiServer.Migration.ObjectStore462
   • EPiServer.MigrationEngine
2. Create a new class and add references to:
   using EPiServer.BaseLibrary;
   using EPiServer.Implementation;
   using EPiServer.Implementation.Serialization;
   using EPiServer.Migration;
   using EPiServer.Migration.ObjectStoreCommon;
3. Implement IMigrationExtension interface.
4. Compile your dll and copy it into the bin folder of EpiServerMigration tool.
5. Modify EPiServerMigrationTool.exe.config by adding a key to handle your custom type.

Here is a short example of custom object migration:

Migrate Other Data in the Database

The migration tool converts the database "in place", meaning that it converts the data and schema of the source database. We therefore recommend that you back up the database before migration.

Migration Of Custom Property

The migration tool manages conversion of custom properties, if there are such properties in the site to be migrated. The tool creates a skeleton for the property and changes the name of the property to AutoGenerated_XXXX. (The XXXX postfix points to the name of custom property before migration.) After migration, the system engineer should change it to the appropriate custom property. The migration tool creates the property on-the-fly, because the real custom property (assembly) does not exist under the new site yet.

Change the customer property back to the original type by following the steps below:

1. Refactor the code of the custom property to CMS 5 API.
2. Copy the assembly or module under bin directory of the new site.
3. Go to Admin mode and select Edit Custom Properties.
4. Change AutoGenerated_XXXX to XXXX name and choose the appropriate Class name and Assembly Name for the property.

After editing all custom properties, you can delete the AutoGenerateCustomProperty.dll from the bin directory under the new site.

Migrate Enterprise Sites

The migration tool adds some entries to web.config for the enterprise settings, but additional manual steps must be done after migration. 

Enter applicationId, siteUrl, utilUri, uiUrl and pageStartId with appropriate information for each site. Here is a code example for these attributes. Tip! If you browse the site, you will receive error code from IIS which points to applicationId, you can use it for applicationId.

Migrate Unified File Systems

In EPiServer CMS 4.62 the file system was based on an EPiServer CMS-specific technology called Unified File System (UFS). In EPiServer CMS 5 the file systems are based on the ASP.NET technology Virtual Path Providers (VPP). The following conversions are carried out by the migration tool:

• EPiServer.FileSystem.Handler.NativeFileSystem -> EPiServer.Web.Hosting.VirtualPathVersioningProvider
• EPiServer.FileSystem.Handler.VersioningFileSystem -> EPiServer.Web.Hosting.VirtualPathVersioningProvider

If the EPiServer CMS 4.62 site uses an IIS virtual directory that maps a relative folder outside the application, that folder must be copied locally relative to the site, e.g. if there is a virtual directory 'files' in IIS under the application that is configured to point to a physical directory outside the application root. The reason for this is that the migration tool does not have any knowledge of IIS settings and hence it cannot locate the physical folder if it is a virtual directory. 

The reason NativeFileSystem is converted to VirtualPathVersioningProvider is that the versioning provider supports permanent links, which EPiServer.Web.Hosting.VirtualPathNativeProvider does not. VirtualPathNativeProvider does not support metadata either. 

Permanent links were introduced with EPiServer CMS 5. The links are stored in the database as a guid-based link based on a unique identifier - can be a versioning file ID or a page ID. This assures that files can be moved around in the file system without affecting the links, i.e. the links will not be broken. If the conversion from NativeFileSystem to VirtualPathVersioningProvider is not wanted, you can comment out that handler in the CMS 4.62 web.config file before migration. Migration tool will also take the folder pointed to by the setting EPsUploadDir and convert it to a VersioningFileSystem. If you do not want to convert that file system you should change EPsUploadDir to point to e.g. an empty folder in 4.62 site root. Then after migration you can add VPP configuration that uses EPiServer.Web.Hosting.VirtualPathNativeProvider for those native filesystems that you choose to not convert.

ASP.NET 2.0 applications restart when, for example, new folders are created under the physical root of the application. Because of this EPiServer CMS 5 sites doe not allow VPPs to be configured with a physical path under the application's physical root. When the migration tool migrates a UFS with a physical root under the application root, it will relocate it to the physical root for VPPs that was given when the CMS 5 R2 site was installed. For UFS handlers that were configured with a physical path outside the application, the migration tool creates the new physical structure in the same location as the UFS system, but in a subfolder Converted (or Converted_1 if Converted already exists). The migration process will not alter the existing filesystem but create new parallell structures. This implies that there must be at least the same amount of disc space free that is used by the UFS filesystems. When the conversion is done, all old files and folders can be removed manually.

The file system migration of NativeFileSystem to VirtualPathVersioningProvider is performed by the migration tool deploying a temporary file ConvertNativeFileSystem.aspx to the CMS 5 site. The migration tool then makes a request for the page, which will then do the work. The reason this is done on the site and not in the migration tool is that the migration of file system requires a web context to execute.

If the migration of file system fails for some reason, for example if the site is not executable or IIS is not startable, the migration process will stop. After making sure the site is up and running, it is possible to continue the migration process by starting the migration tool again and selecting to continue the existing migration process. 

It is possible to configure the file migration to skip certain subfolders. To do this, the file excludedFolders.config should be deployed to the target site root before migration. The following is an example of configuration that skips migration of subfolder "subfolder1" in a file system with root "upload" and a subfolder "subfolder2" that is further down in the file system hierarchy.

Migrate Custom Unified FileSystems

The migration tool will take care of conversion for the unified file systems EPiServer.FileSystem.Handler.NativeFileSystem and EPiServer.FileSystem.Handler.VersioningFileSystem. They will be converted to VirtualPath provider of type EPiServer.Web.Hosting.VirtualPathVersioningProvider. Other unified file systems will not be converted to a corresponding VirtualPath provider. It is though possible to convert custom unified file systems by setting up an event handler for the event MigrateCustomFileSystem on class MigrationEvents. The event handler will then be called for each custom file system that is registered on the 4.62 site. Download a code sample for a module that converts a custom file system to a corresponding virtual path provider.

Change LongString Properties to XhtmlString

Permanent link support in CMS 5 requires that the property is of type XhtmlString. The migration offers the opportunity to convert LongString properties to XhtmlString properties. Before the migration starts, the migration tool displays a list of all LongString properties so that the user can select which properties to convert. The benefit of XHtmlString compared to LongString is that XHtmlString supports permanent links and dynamic content. On the other hand is LongString property faster to load (since it does not need to be parsed). So the suggestion is to convert those LongString properties that might include links.

Migrate Links

Links in CMS 5 are stored in the database as a guid-based link based on a unique identifier - can be a file ID or a page ID. This allows, for example, files to be moved without breaking any existing links. The migration tool tries to rewrite all links in content as permanent links. This step is one of the last steps in the migration and is achieved by the migration tool deploying a temporary file ConvertLinks.aspx to the CMS 5 site. The migration tool then makes a request for the page, which will then do the work. The reason this is done on the site and not in the migration tool is that link migration requires a web context to execute.

If the CMS 4.62 site to migrate is a site configured as a virtual directory, the physical path of the virtual directory should be relocated to the targeting CMS 5 site before migration. The reason for this is that in CMS 4.62 running in a virtual directory, a link to a local resource is stored as "/virdir/Documents/image.gif". So when the migration of links work is performed, the CMS 5 site must run under the same virtual directory, otherwise the VPP configured for virtualpath '~/Documents' will not handle the request. This will result in the link not being rewritten to a permanent link.

If the migration of links fails for some reason, for example if the site is not executable or IIS is not startable, the migration process will stop. After making sure the site is up and running, it is possible to continue the migration process by starting the migration tool again and selecting to continue the existing migration process. 

Migrate Page Types

Migration deploys temporary .aspx files on the target site according to the page types on the source site. The deployed .aspx site will only list all properties on the page and have some navigation. So after migration it is possible to browse the site.

What Happens After Migration?

After data has been migrated, the code needs to be migrated. This means that code for page templates, properties, plug-ins, etc. must be converted to EPiServer CMS 5 API. The section Code Conversion in the tech note Migrating from CMS 4.62 to CMS 5 R1 describes  some of the changes in the API that need to be considered during the code migration.

Troubleshooting

There is a reported error in .NET framework that can occur when a virtual path contains some characters (e.g. ':'), this is reported in KB932522. This can cause link migration to fail for some pages. Any errors during the link migration will be logged to a file MigrateLinksErrors.txt that will be created in the site root of the target CMS 5 site. Then after the migration those pages can be migrated manually by open them in edit mode and republish them. 

The migration requires that the database collation is the same for the database and each text-based column in tables, which is the case when site is installed with EPiServer CMS Manager. The reason for this is that during migration new tables will be created with the same collation as the database. The creation of stored procedures will fail if it tries to do a join on two text-based columns with different collation. If the collation differs, the database should be changed before migration so collation is the same.

The link migration step reads pages including properties from the database and stores the updated values. For large sites this may cause an error in the form of an SQL timeout. The reason for this is that the database read and write operations work on the same tables and if there are a lot of entries in the SQL server, some read and write operations can block each other. In that case migration will be stopped. Since the migration process stores the state of the migration, the migration tool can be restarted and will continue migration where it was canceled.

"The partner transaction manager has disabled its support for remote/network transactions"

If you are receiving the exception: "[Error] System.Transactions.TransactionException: The partner transaction manager has disabled its support for remote/network transactions," see the migration tool FAQ - there are some steps described there that may be of assistance.

EPiServer 4.62 Assemblies with Version Numbers