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

Ensure you have a good backup of both site and database.
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.
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.
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.
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").
Merge your existing settings from the old configuration into web.config (see the section "Migrating Configuration").
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:

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.
Remove all EPiServer.Common.* binaries from bin folder
Remove all EPiServer.Community.* binaries from bin folder
Remove all EPiServer.Mail.* binaries from bin folder
Delete EPiServerCommunity folder from web root
Delete EPiServerMail folder from web root
Remove these virtual directories from IIS:
/EPiServerCommunity/Modules/ImageGallery/Thumbnails
/EPiServerCommunity/Modules/DocumentArchive/Files
/EPiServerCommunity/Modules/Forum/Icons
In web.config, remove the hibernate-configuration element.
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 Community 3.2	EPiServer Community 4.0
BlogHandler.AddBlog(...)	BlogHandler.Instance.AddBlog(...)

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.

EPiServer Community 3.2	EPiServer 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; ClubHandler.Instance.UpdateClub(someClub);

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.2	EPiServer 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 ...)

EPiServer.Common.Content.IContent

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

EPiServer Community 3.2	EPiServer 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.2	EPiServer 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

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.

EPiServer Community 3.2	EPiServer 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.2	EPiServer 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"; 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 Community 3.2	EPiServer 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.

Miscellaneous

EPiServer Community 3.2	EPiServer Community 4.0	Comment
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.

Deletions

Removed EPiServer.Common namespace/class/property	Comment
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.

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:

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

Element/Attribute	Comment
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

Element/Attribute	Comment
/sites/site [hostName] attribute	Renamed to siteId

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

Element/Attribute	Comment
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"> <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.

Try our conversational search powered by Generative AI!