SaaS CMS has officially launched! Learn more now.

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

Product version:

EPiServer Community 3.2, 4.0 EPiServer Mail 4.4, 5.0

Document last saved:

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. 

      <site hostName="Default">
            thumbnailVirtualFilePath="~/EPiServerCommunity/Modules/ImageGallery/Thumbnails" ... />
            virtualPath="/EPiServerCommunity/Modules/DocumentArchive/Files" />
            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:
  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">

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 Community 3.2EPiServer Community 4.0
BlogHandler.AddBlog(...) BlogHandler.Instance.AddBlog(...)



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.

EPiServer Community 3.2EPiServer Community 4.0
Blog.Active Blog.Status == EntityStatus.Approved
ContactRelation.ContactType == ContactType.Request ContactRelation.Status == EntityStatus.Pending
ContactRelation.ContactType == ContactType.Contact ContactRelation.Status == EntityStatus.Approved
Club.Removed Club.Status == EntityStatus.Removed
RoomBase.Removed RoomBase.Status == EntityStatus.Removed
User.Removed User.Status == EntityStatus.Removed
// Temporarily remove club
ClubHanlder.RemoveClub(someClub, false);
someClub.Status = 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 Community 3.2EPiServer Community 4.0
new NewsFeedStory(..., IUser user, ...) new NewsFeedStory(..., IAuthor actor, ...)
NewsFeedHandler.AddStoryToActorFeed(NewsFeedStory story) NewsFeedHandler.Instance.PublishStory(NewsFeed newsFeed, NewsFeedStory story)
NewsFeedHandler.GetNewsFeed(...) NewsFeedHandler.Instance.GetNewsFeedStories(NewsFeedType.NewsFeed ...)
NewsFeedHandler.GetActorFeed(...) NewsFeedHandler.Instance.GetNewsFeedStories(NewsFeedType.MiniFeed ...)



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

EPiServer Community 3.2EPiServer Community 4.0
Blog.Name Blog.Header
Blog.PresentationText Blog.Body
Club.Description Club.Body
Club.Name Club.Header
Entry.Content Entry.Body
Entry.Title Entry.Header
EntryComment.Comment EntryComment.Body
EntryComment.Title EntryComment.Header
Event.Description Event.Body
Event.Name Event.Header
Image.Description Image.Body
Image.Name Image.Header
Image.UploadDate Image.Created
Image.Uploader Image.Author
ImageCommentSortField.CommentDate ImageCommentSortField.Created
ImageGallery.Description ImageGallery.Body
ImageGallery.Name ImageGallery.Header
ImageSortField.UploadDate ImageSortField.Created
MessageBase.Sender MessageBase.Author
MessageBase.Subject MessageBase.Header
Reply.ChangeDate Reply.Modified
Reply.CreateDate Reply.Created
Reply.Subject Reply.Header
Reply.Text Reply.Body
Room.Description Room.Body
Room.Name Room.Header
Topic.ChangeDate Topic.Modified
Topic.CreateDate Topic.Created
Topic.Subject Topic.Header
Video.Name Video.Header
Video.Description Video.Body
Video.UploadDate Video.Created


Methods have moved to the Handler classes

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

EPiServer Community 3.2EPiServer Community 4.0
Blog.GetEntries BlogHandler.Instance.GetEntries
BlogEntry.GetComments BlogHandler.Instance.GetEntryComments
Calendar.GetEvents CalendarHandler.Instance.GetEvents
Club.GetMembers ClubHandler.Instance.GetMembers
ContactContainer.GetContacts ContactHandler.Instance.GetContacts
Entry.GetNumVisits VisitHandler.Instance.GetNumVisits
Event.GetRegistrations CalendarHandler.Instance.GetRegistrations
Image.GetComments ImageGalleryHandler.Instance.GetImageComments
Image.GetNumVisits VisitHandler.Instance.GetNumVisits
Image.GetThumbnail ImageGalleryHandler.Instance.GetThumbnail
ImageGallery.GetImages ImageGalleryHandler.Instance.GetImages
RoomBase.GetTopics ForumHandler.Instance.GetTopics
Topic.GetNumVisits VisitHandler.Instance.GetNumVisits
Video.GetNumVisits VisitHandler.Instance.GetNumVisits



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.

EPiServer Community 3.2EPiServer Community 4.0
ImageGallery gallery = ImageGallery(name, text, parentImageGallery, site); ImageGallery gallery = ImageGallery(header, body, author);
gallery.Parent = parentImageGallery;


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.

EPiServer Community 3.2EPiServer Community 4.0
ContactHandler.GetContactContainer(..., ISite site, ...) ContactHandler.Instance.GetContactContainer(..., ICategory category, ...)
new EntityTag(ITag tag, IAuthor author) new EntityTag(ITag tag, ICategory category, IAuthor author)


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";



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 Community 3.2EPiServer Community 4.0
new NewsFeedStory(..., IUser user,...) new NewsFeedStory(..., IAuthor actor, ...)


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.


EPiServer Community 3.2EPiServer Community 4.0Comment
FrameworkFactoryBase.GetTypeName EntityProviderHandler.Instance.GetTypeName GetTypeName has been moved from FrameworkFactoryBase to EntityProviderHandler.Instance.
IUser.PassWord IUser.Password Slight change of the property name.
OnlineStatusModule.[Method] OnlineStatusHandler.Instance.[Method] The events and static methods of OnlineStatusModule have been moved to the new OnlineStatusHandler class.



Removed EPiServer.Common namespace/class/propertyComment
Publishing.PublishState class Replaced by EPiServer.Common.EntityStatus.
Replication namespace Namespace has been completely removed.
Visits.VisitableEntityCollection class Removed and replaced by EPiServer.Common.EntityCollection.
Chat namespace Namespace has been completely removed.
Club.ClubApproval class EPiServer.Common.EntityStatus
ConnectionLink namespace Namespace has been completely removed.
Forum.Reply.Changed.Set accessor The Changed property is now read-only.
Forum.Reply.IP property Removed.
Forum.Topic.Changed.Set accessor The Changed property is now read-only.
Forum.Topic.IP property Removed.
Moblog namespace Namespace has been completely removed.

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.


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

siteHosts element Removed, all site host configuration is now based on episerver.framework/siteHostMapping
/siteHosts/add [connectionStringName] attribute Moved to episerver.common/sites/site [connectionStringName]
/sites/site [hostName] attribute Renamed to episerver.common/sites/site [siteId]
/sites/site/activityLog/loggedTypes element The element for EPiServer.Community.Club.Ad should be removed from the list.
/sites/site/administration/administrableTypes element The element for EPiServer.Community.Club.Ad should be removed from the list.
/sites/site/connectionLink element Removed.
/sites/site/integration/session element Removed.
/sites/site/moblog element Removed, EPiServer Community 4 does not have a Moblog module.
/sites/site/replication element Removed, replication is now handled using the EPiServer Events system and is set up in the related WCF configuration.
/sites/site/security [defaultPasswordProvider] attribute Attribute renamed to defaultProvider


Changes to the <episerver.mail> configuration section

/sites/site [hostName] attribute Renamed to siteId


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

BlogRootCategory Removed.
ClubRootCategory Removed.
ImageGalleryRootCategory Removed.
MyPageRootCategory Removed.
RelateRootCategory New.
VideoGalleryRootCategory Removed.


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

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


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

<location path="EPiServerCommunity/Public">
         <allow users="*" />


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

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


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

   <assemblyIdentity name="EPiServer.Community.Moblog.ContentProviders.Unwire" publicKeyToken="8fe83dea738b45b7" culture="neutral" />
   <bindingRedirect oldVersion="" newVersion="3.2.517.24" />
   <assemblyIdentity name="EPiServer.Community.Moblog" publicKeyToken="8fe83dea738b45b7" culture="neutral" />
   <bindingRedirect oldVersion="" newVersion="3.2.517.24" />
   <assemblyIdentity name="EPiServer.Community.ConnectionLink" publicKeyToken="8fe83dea738b45b7" culture="neutral" />
   <bindingRedirect oldVersion="" newVersion="3.2.517.24" />
   <assemblyIdentity name="EPiServer.Common.Replication" publicKeyToken="8fe83dea738b45b7" culture="neutral" />
   <bindingRedirect oldVersion="" newVersion="2.3.517.36" />
   <assemblyIdentity name="EPiServer.Common.Security.Internal" publicKeyToken="8fe83dea738b45b7" culture="neutral" />
   <bindingRedirect oldVersion="" newVersion="2.3.517.36" />
   <assemblyIdentity name="EPiServer.Common.Services.Replication.Shared" publicKeyToken="8fe83dea738b45b7" culture="neutral" />
   <bindingRedirect oldVersion="" newVersion="2.3.517.36" />
   <assemblyIdentity name="EPiServer.Common.Services.Replication.Subscriber" publicKeyToken="8fe83dea738b45b7" culture="neutral" />
   <bindingRedirect oldVersion="" newVersion="2.3.517.36" />
   <assemblyIdentity name="EPiServer.Wsrp" publicKeyToken="8fe83dea738b45b7" culture="neutral" />
   <bindingRedirect oldVersion="" newVersion="5.2.375.236" />
   <assemblyIdentity name="EPiServer.Mail.Install" publicKeyToken="8fe83dea738b45b7" culture="neutral" />
   <bindingRedirect oldVersion="" newVersion="4.4.343.20" />