Migrating EPiServer Community 3.2 to 4.0 and EPiServer Mail 4.4 to 5.0

Migration Step Overview

1. Ensure you have a good backup of both site and database.
2. Arrange for a second database with the new versions installed that you can then migrate to. This will involve installing the relevant products (Community, Mail or the entire Relate+ package) using the EPiServer Deployment Center. For further details on your options see the "Migrating the Database" section.
3. Open the SQL migration script in SQL Server Management Studio, set the variables @strSourceDB (the database of the site that is being migrated) and @strTargetDB (the database of the new site) and run the SQL migration script (see Migrating the Database for further information). Note that these two databases must reside on the same SQL Server.
4. Copy the existing code files/pages from the old site to the new site. If you are migrating to Relate+ 2, you may choose to only transfer your own customizations.
5. Update any old code files/pages to so that the files comply with the updated APIs of EPiServer Community and EPiServer Mail (see the sections "Migrating EPiServer Community 3.2 to EPiServer Community 4.0" and "Migrating EPiServer Mail 4.4 to EPiServer Mail 5.0").
6. Merge your existing settings from the old configuration into web.config (see the section "Migrating Configuration").
7. Final step is to migrate the image galleries, document archives etc to the new site. You got two options:
   a. Move the files to the locations that were set up when you installed the new site. You can find the locations in web.config. See below.
   b. If you don't want to move the files you can instead change the attributes in the relevant elements in web.config and modify the virtual directories in IIS to point to the existing locations. See below. 

<episerver.community>
   <sites>
      <site hostName="Default">
         ...
         <imageGallery
            imageAbsoluteFilePath="[locationOfYourImages]"
            thumbnailVirtualFilePath="~/EPiServerCommunity/Modules/ImageGallery/Thumbnails" ... />
         ...
         <documentArchive 
            physicalPath="[locationOfYourDocuments]"
            virtualPath="/EPiServerCommunity/Modules/DocumentArchive/Files" />
         ...
         <webmail
            diskCachePath="[locationOfYourWebmailCacheFiles]" ... />

These virtual directories that are automatically set up during installation:

• /EPiServerCommunity/Modules/ImageGallery/Thumbnails
• /EPiServerCommunity/Modules/DocumentArchive/Files 

If you are migrating from a database that has EPiServer Community 3.2 SP1 as well as EPiServer CMS and want to maintain them sharing one database you have two options: 

Option 1

Install the new version of all relevant products to a new database (Relate+ 2 package, CMS6, Community4, Mail5 or any desirable combination of these) to a new database, then use the community database migration script to transfer the Community data over, export relevant CMS data from the original site and import that into the destination. This option gives you the easiest migration process and the new Relate+ 2 site should continue to work after migrating your data. The documentation on code and configuration adaptations will in this case only apply to any modifications you transfer over.

Option 2

Clone the original database, upgrade CMS to CMS6 (if applicable), remove all Community, Common and Mail objects from the database by running the "Drop Relate tables.sql" script (remove tables, sprocs, functions and views matching *EPiServerCommon*, *EPiServerCommunity*, *EPiServerMail*), remove product files from site (see below), install Community4 and/or Mail5 as appropriate, then migrate from the original database to the cloned and modified one.

This migration option has the advantage of fully maintaining CMS data, which is probably best if you have made a complete custom site or have made major changes from Relate+ templates while the former would be preferrable if you want to start from the new Relate+ 2 templates.

The following steps will be required to remove old product files from the site and objects from database prior to continuing:

1. Change the value of @strTargetDB in "Drop Relate tables.sql" to the name of the database where you want to remove all the Community objects, then run the SQL script.
2. Remove all EPiServer.Common.* binaries from bin folder
3. Remove all EPiServer.Community.* binaries from bin folder
4. Remove all EPiServer.Mail.* binaries from bin folder
5. Delete EPiServerCommunity folder from web root
6. Delete EPiServerMail folder from web root
7. Remove these virtual directories from IIS:
   /EPiServerCommunity/Modules/ImageGallery/Thumbnails
   /EPiServerCommunity/Modules/DocumentArchive/Files
   /EPiServerCommunity/Modules/Forum/Icons
8. In web.config, remove the hibernate-configuration element.
9. Open EPiServer Deployment Center, select Install Community On Existing Site.

During installation, if you do not want to move files around, select the same folder for "user contributed files" as before. By default, it is located at: C:\EPiServer\VPP\<site>\EPiServerCommunity.

Migrating the Database

The database migration script will allow you to copy data from a EPiServer Mail 4.4 and/or EPiServer Community 3.2 installation to a pristine installation of EPiServer Mail 5.0 and/or EPiServer Community 4.0. The script requires that the EPiServer Mail and/or EPiServer Community database schema are of the correct version and that the tables of your target database have not changed since installation (do not use the new database prior to migration!). If the requirements are not met, the SQL script will abort and output an error message.

Open the SQL script in SQL Server Management Studio and connect using credentials that have (at least) read access to the tables in the source database and read/write access to the tables in the target database.

Set @strSourceDB to the name of the database of the site that is being migrated and @strTargetDB to the name of the target database.

Set @bitMigrateMail and @bitMigrateCommunity (0 = no, 1 = yes) depending on which products you wish to migrate. Please note that if you want to migrate both, you have to do so in one operation. Migrating first one and then the other is not supported.

Set @bitRestoreRelatePlusData depending on if you want to use the Relate+ templates on the target site or not (0 = migrate to plain Community site, 1 = migrate to Relate+ site). If you choose to migrate to a Relate+ site, the following applies:

The Relate+ templates is a specific implementation of EPiServer Community, which means that some data from an existing EPiServer Community 3.2 environment may not be usable by the Community implementation in the Relate+ templates, or may be presented differently than it was on the source site. If you want to do this, you can modify/extend the Relate+ templates to suit your needs.

During the migration some Relate+ default data will be removed and restored afterwards. Since identity values may have changed, this requires some changes to be performed:

When Relate+ is installed it automatically creates a root forum called 'Root Forum' and it has the id 1. Which forum to use as the root forum is configured in the web.config as shown below:

<setting name="RootForumId" serializeAs="String">
   <value>1</value>
</setting>

When the Relate+ default data is restored, the Root Forum will get a new id and this value should be entered in the web.config. The new id that should be set in web.config is displayed as output at the end of the script execution.

Once you have set all the script variables according to your needs go ahead an execute the script. Carefully look through the output before continuing.

EPiServerCommunity code migration 

Changes and Additions to the API

Handler classes have Instance properties

All Handler classes now have static instances which are accessed via the Instance property. All Handler methods should be called via the static Handler instance. Example:

EPiServer.Common.IEntityStatus

EntityStatus is a new interface introduced in EPiServerCommon. The interface includes the Status property (of type EntityStatus) which now replaces all of the Entity-specific states. EntityStatus is an enum with three different values, Approved / Pending / Removed. In most of the get-methods in the handlers you can now use EntityStatus as a parameter. Some Remove methods had overloads that accepted a boolean parameter to signify wether the Entity should be permanently or temporarlily removed. These overloads have been removed - temporary deletions are now handled by setting the Entity's Status property to EntityStatus.Removed.

NewsFeeds and NewsFeedStories

EPiServer Community 4 introduces the NewsFeed class. This class represents the user's newsfeed which can be NewsFeedType.NewsFeed (contains friends' stories) or NewsFeedType.Minifeed (contains the user's own stories). An instance of this class will be needed when publishing stories. There has also been changes to NewsFeedStorys, in EPiServer Community 4 they can be created for an IAuthor (AnonymousAuthor, UserAuthor, etc.) rather than an IUser. This allows for NewsFeedStories to be created for visitors that are not logged in.

EPiServer.Common.Content.IContent

IContent is a new interface that normalizes the names of properties that are common to many Entities. Examples:

Methods have moved to the Handler classes

Some methods that were called from Entity instances have been moved to the Handler classes. Examples:

Constructors

Contructors have been cleaned up, as far as possible there are now only one contructor for every class with the required parameters. Values that no longer can be set via constructor parameters should now be set via properties on the constructed Entity.

Site partitioning

Sites have been removed in favour of the category system, partitioning of content is now achieved by adding categories to an Entity's Category collection. Methods exist for retrieving Entities based on their categorization.

Owner system

Now entities can own and be owned by other entities. The owning Entity is set via the OwnedBy property. Example: 

Poll poll = PollHandler.Instance.GetPoll(123);
ImageGallery gallery = (ImageGallery)ImageGalleryHandler.Instance.GetImageGallery(456).Clone();

gallery.OwnedBy.Entity = poll;
gallery.OwnedBy.Context = "Image gallery for poll";

ImageGalleryHandler.Instance.UpdateImageGallery(gallery);

User -> IAuthor (new UserAuthor)

Generalization of authorship. Entities that had to have a IUser to be constructed now allow for IAuthor instead, like AnonymousAuthor, UserAuthor, Guest Author etc.. Examples:

EPiServer.Common.Security and EPiServer.Common.Security.Internal have been merged

SecurityHandler has been made into a normal handler, User and Group are created using the normal public constructors for these classes. PendingUser has been obsoleted by the IEntityStatus system.

Miscellaneous

Deletions

   
EPiServerMail Code Migration

Site, ISite, SiteHandler, SiteCollection, etc that used to exist in EPiServer.Common have moved to EPiServer.Mail.Core.Site

UriProvider required

A URI provider will be required for some functionality (incl. some admin features) to work. Relate+ 2.0 comes with a URI provider that fits with the site structure for that site. If you are going to use Community 4 with a different site than Relate+ 2, or a customized version of Relate, that site will need its own URI provider. See Templates\RelatePlus\CommunityModules\UriProvider.cs as reference.

Search

The new search functionality uses an index of its own which needs to be populated with any existing data for search to work. A separate tool, ReindexRelatePlus2.aspx, is included that will queue existing entities for indexing. Please note that the new web site must be able to start up and UriProviders must be configured for the tool to work. Put this tool in the root folder of the new web site and browse to it to trigger (re)indexing.

Migrating Configuration

This is an overview of the changes to the configuration file between Common 2.3 SP1, Community 3.2 SP1, Mail 4.4 SP1, Relate+ 1.0 SP1 and Common 4.0, Community 4.0, Mail 5.0 and Relate+ 2.0

While this section will describe the necessary changes, it is recommended to have the default configuration for the new version as reference. Config file excerpts included in this section are based on defaults from a Relate+ 2 setup. Some customization may be necessary depending on your environment.

These are the http modules required in a Relate+ 2 setup:

<add name="InitializationModule" preCondition="managedHandler"
   type="EPiServer.Framework.Initialization.InitializationModule, EPiServer.Framework" />

<add name="EPiServerCommon" preCondition="managedHandler"
   type="EPiServer.Common.Web.HttpModule, EPiServer.Common.Web" />

<add name="EPiServerCommunity" preCondition="managedHandler"
   type="EPiServer.Community.Web.Administration.CommunityModule, EPiServer.Community.Web.Administration" />

<add name="EPiServerMail" preCondition="managedHandler"
   type="EPiServer.Mail.Core.Web.MailModule, EPiServer.Mail.Core.Web" />

The http modules EPiServer.Community.Web.CmsIntegration.HttpModule as well as EPiServer.Templates.RelatePlus.HttpModules.CmsIntegrationModule should be removed if they are in the list.

EPiServerCommonIntegrationMembershipProvider has been deprecated (but remains available), replaced by IntegrationHttpModule and integration configuration

Changes to the <episerver.common> configuration section

Changes to the <episerver.mail> configuration section

Changes to the Relate+ configuration settings (<applicationSettings>)

location[path="EPiServerCommunity"] should have access allowed only for select roles (ie, CommunityAdmins, CommunityModerators)

<location path="EPiServerCommunity">
   <system.web>
      <authorization>
         <allow roles="CommunityAdmins,CommunityModerators,Administrators" />
         <deny users="*" />
      </authorization>
   </system.web>
</location>

location[path="EPiServerCommunity/Public"] should have access allowed for everyone

<location path="EPiServerCommunity/Public">
   <system.web>
      <authorization>
         <allow users="*" />
      </authorization>
   </system.web>
</location>

location[path="EPi/UI"]/system.web/authorization roles should have CommunityAdmins and CommunityModerators added

<authorization>
   <allow roles="WebEditors, WebAdmins, Administrators, CommunityAdmins,CommunityModerators,Administrators" />
   <deny users="*" />
</authorization>

The following assemblies should be removed from /runtime/assemblyBinding/. The same assemblies should be removed from the bin folder as well.

<dependentAssembly>
   <assemblyIdentity name="EPiServer.Community.Moblog.ContentProviders.Unwire" publicKeyToken="8fe83dea738b45b7" culture="neutral" />
   <bindingRedirect oldVersion="3.0.0.0-3.65535.65535.65535" newVersion="3.2.517.24" />
</dependentAssembly>
<dependentAssembly>
   <assemblyIdentity name="EPiServer.Community.Moblog" publicKeyToken="8fe83dea738b45b7" culture="neutral" />
   <bindingRedirect oldVersion="3.0.0.0-3.65535.65535.65535" newVersion="3.2.517.24" />
</dependentAssembly>
<dependentAssembly>
   <assemblyIdentity name="EPiServer.Community.ConnectionLink" publicKeyToken="8fe83dea738b45b7" culture="neutral" />
   <bindingRedirect oldVersion="3.0.0.0-3.65535.65535.65535" newVersion="3.2.517.24" />
</dependentAssembly>
<dependentAssembly>
   <assemblyIdentity name="EPiServer.Common.Replication" publicKeyToken="8fe83dea738b45b7" culture="neutral" />
   <bindingRedirect oldVersion="2.0.0.0-2.65535.65535.65535" newVersion="2.3.517.36" />
</dependentAssembly>
<dependentAssembly>
   <assemblyIdentity name="EPiServer.Common.Security.Internal" publicKeyToken="8fe83dea738b45b7" culture="neutral" />
   <bindingRedirect oldVersion="2.0.0.0-2.65535.65535.65535" newVersion="2.3.517.36" />
</dependentAssembly>
<dependentAssembly>
   <assemblyIdentity name="EPiServer.Common.Services.Replication.Shared" publicKeyToken="8fe83dea738b45b7" culture="neutral" />
   <bindingRedirect oldVersion="2.0.0.0-2.65535.65535.65535" newVersion="2.3.517.36" />
</dependentAssembly>
<dependentAssembly>
   <assemblyIdentity name="EPiServer.Common.Services.Replication.Subscriber" publicKeyToken="8fe83dea738b45b7" culture="neutral" />
   <bindingRedirect oldVersion="2.0.0.0-2.65535.65535.65535" newVersion="2.3.517.36" />
</dependentAssembly>
<dependentAssembly>
   <assemblyIdentity name="EPiServer.Wsrp" publicKeyToken="8fe83dea738b45b7" culture="neutral" />
   <bindingRedirect oldVersion="5.0.0.0-5.65535.65535.65535" newVersion="5.2.375.236" />
</dependentAssembly>
<dependentAssembly>
   <assemblyIdentity name="EPiServer.Mail.Install" publicKeyToken="8fe83dea738b45b7" culture="neutral" />
   <bindingRedirect oldVersion="4.0.0.0-4.65535.65535.65535" newVersion="4.4.343.20" />
</dependentAssembly>