Views: 17376
Number of votes: 2
Average rating:

Migrating StarCommunity 3.1 to EPiServer Community 3.2 and EPiServer Mail 4.3 to 4.4

The process of migrating can generally be summarized into five steps. Read about how to migrate StarCommunity 3.1 to EPiServer Community 3.2 and EPiServer Mail 4.3 to 4.4.

 

Overview

The process of migrating can generally be summarized into five steps:

  1. Install a target site with EPiServer Community 3.2 and/or EPiServer Mail 4.4
  2. Run the database migration script
  3. Move and update your project code
  4. Merge the old and new configuration files
  5. Migrate the non-code files (images, documents etc.)

Install target site

Install a new site using the EPiServer Deployment Center. This site should have the target versions of the products you are migrating. This means that you may want to install any or all of EPiServer CMS, Community 3.2 and Mail 4.4, either alone or as parts of a package such as Relate+.

In order to migrate the database information both the source and target databases need to exist on the same database server. Make sure to specify the correct database server during the database step of the installation wizard.

Note: You should avoid logging in to your target site once it has been installed. Logging in will generate a new row in the tblEPiServerCommunityOnlineStatusLog table and the next step of the migration requires all tables to be empty. If you have logged in you need to empty the tblEPiServerCommunityOnlineStatusLog before continuing.

 

Run database migration script

Download the database migration script available from the download section.

The supplied SQL script will allow you to copy data from a EPiServer Mail 4.3 and/or StarCommunity 3.1 installation to an untouched installation of EPiServer Mail 4.4 and/or EPiServer Community 3.2. 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 are empty. If the requirements are not met, the SQL script will abort and output an error message.

Open the SQL migration script in SQL Server Management Studio and connect to the database server using credentials that have at least read access to the tables in the source database and 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 (which was installed in the previous step).

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 @bitDebug depending on if you wish to print debug information during the script execution. It is recommended that you keep the value set to 1.

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 StarCommunity 3.1 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.

 

Move and update your project code

Copy all your project files from the old site to the new site. Do not copy the EPiServer CMS/Community/Mail files and assemblies.

Open the copied project in Visual Studio.

Community 3.2 and Mail 4.4 now rely on .NET Framework 3.5. You should go into the Properties for your web project, and in there change the target framework version (Application -> Target Framework -> .NET Framework 3.5). The Community 3.1 and Mail 4.3 versions used System.Web.Extensions 1.0 for AJAX functionality. This extra assembly is no longer required with the new versions as these use the 3.5 version. If you use MS AJAX in your application too, you should change any existing System.Web.Extensions 1.0 references in your application to System.Web.Extensions 3.5.

Migrating StarSuite to EPiServer Common Framework

Start by updating your project references according to this table.

StarSuite assembly ...has been renamed to
StarSuite.Core.Licensing  EPiServer.Common.Licensing
StarSuite.Core.ComponentArt.Web.UI  EPiServer.Common.ComponentArt.Web.UI
StarSuite.Core.Cache EPiServer.Common.Cache
StarSuite.Core  EPiServer.Common.Framework.Impl
StarSuite.Core.Web.Authorization  EPiServer.Common.Web.Authorizarion
StarSuite.Core.Data EPiServer.Common.Data
StarSuite.Modules.Replication EPiServer.Common.Replication
StarSuite.Security EPiServer.Common.Security
StarSuite.Security.Internal EPiServer.Common.Internal
StarSuite.Services.Replication.Subscriber EPiServer.Common.Services.Replication.Subscriber
StarSuite.Services.Replication.Shared EPiServer.Common.Services.Replication.Shared

 

Assembly names and namespaces have been changed to reflect the new product names and some classes and interfaces have been moved to a more appropriate assemblies in order to separate the interfaces and the implementation of the classes. In some cases, namespaces have been merged but most changes can be performed using a "Replace in Files" operation. First up is the StarSuite.Core.Modules namespace:

Replace ...with
StarSuite.Core.Modules EPiServer.Common


For the most part, the StarSuite.Core.Modules namespace have been moved to EPiServer.Common. However, note that the following classes have the 'Modules' part of the namespace intact:

StarSuite.Core.Modules class ...is now located in
IModule  EPiServer.Common.Modules.IModule
ModuleCollection EPiServer.Common.Modules.ModuleCollection
ModuleDependencyAttribute EPiServer.Common.Modules.ModuleDependencyAttribute
ModuleDisplayAttribute EPiServer.Common.Modules.ModuleDisplayAttribute
ModuleEnumerator  EPiServer.Common.Modules.ModuleEnumerator
ModuleTreeNodeCollection EPiServer.Common.Modules.ModuleTreeNodeCollection
ModuleTreeNodeEnumeration  EPiServer.Common.Modules.ModuleTreeNodeEnumeration


One of the classes in the StarSuite.Core.Modules.Security namespace has changed name completely:

StarSuite.Core.Modules.Security class ...has been renamed and moved to
SecurityHandler  EPiServer.Common.Security.EntitySecurityHandler
 

Next up is the StarSuite.Core namespace:

Replace ...with
StarSuite.Core EPiServer.Common


All remaining occurrences of "StarSuite.Core" have been replaced by "EPiServer.Common", but note that the following classes have been renamed:

StarSuite.Core class ...has been renamed and moved to
StarSuite.Core.StarSuiteEventArgs  EPiServer.Common.EPiServerCommonEventArgs
StarSuite.Core.StarSuiteEventHandler EPiServer.Common.EPiServerCommonEventHandler


The remaining StarSuite namespaces can be handled with "Replace in Files" operations:

Replace ...with
StarSuite.Modules EPiServer.Common
StarSuite.Security EPiServer.Common.Security
StarSuite.Services.Replication EPiServer.Common.Services.Replication

 

Migrating StarCommunity to EPiServer Community

Update your project's references to the new assemblies. The assemblies previously named "StarCommunity.Modules.*.dll" is replaced by "EPiServer.Community.*.dll", removing "Modules" from the namespace as well as updating the product name.

StarCommunity assembly ...has been renamed to
StarCommunity.Modules.Blog EPiServer.Community.Blog
StarCommunity.Modules.Calendar EPiServer.Community.Calendar
StarCommunity.Modules.Chat  EPiServer.Community.Chat
StarCommunity.Modules.Club  EPiServer.Community.Club
StarCommunity.Modules.ConnectionLink  EPiServer.Community.ConnectionLink
StarCommunity.Modules.Contact EPiServer.Community.Contact
StarCommunity.Modules.Contest EPiServer.Community.Contest
StarCommunity.Modules.DirectMessage EPiServer.Community.DirectMessage
StarCommunity.Modules.DocumentArchive EPiServer.Community.DocumentArchive
StarCommunity.Modules.Expert EPiServer.Community.Expert
StarCommunity.Modules.Forum EPiServer.Community.Forum
StarCommunity.Modules.ImageGallery EPiServer.Community.ImageGallery
StarCommunity.Modules.Moblog EPiServer.Community.Moblog
StarCommunity.Modules.MyPage EPiServer.Community.MyPage
StarCommunity.Modules.NML EPiServer.Community.NML
StarCommunity.Modules.OnlineStatus EPiServer.Community.OnlineStatus
StarCommunity.Modules.Poll EPiServer.Community.Poll
StarCommunity.Modules.StarViral EPiServer.Community.StarViral
StarCommunity.Modules.VideoGallery EPiServer.Community.VideoGallery
StarCommunity.Modules.Webmail EPiServer.Community.Webmail


In code, this change may be performed by simply performing a "Replace in Files" operation of the following substrings:

Replace ...with
StarCommunity.Modules EPiServer.Community

 

As a part of the refactoring of StarCommunity to EPiServer.Community some parts of the product have been moved and merged into EPiServer.Common and a few classes have changed name to fit their new location. One notable change is that there is only one type of users now, the EPiServer.Common.Security.IUser instead of StarCommunity.Core.Modules.Security.IUser and StarSuite.Core.Security.IUser. The changes may be summarized as follows:

The functionality in ...has been replaced/merged with
StarCommunity.Core.Modules EPiServer.Common.Framework
StarCommunity.Core.Modules.Impl EPiServer.Common.Framework.Impl
StarCommunity.Core.Exceptions EPiServer.Common.Framework.Exceptions
StarCommunity.Security EPiServer.Common.Security
StarCommunity.Security.Internal EPiServer.Common.Security.Internal

 

In code, the namespace changes may be performed by simply performing a "Replace in Files" operation of the following substrings:

Replace ...with
StarCommunity.Core.Modules EPiServer.Common
StarCommunity.Core.Exceptions EPiServer.Common.Exceptions
StarCommunity.Security EPiServer.Common.Security
StarCommunity.Core EPiServer.Community

 

Some of the classes in StarCommunity has changed name completely:

StarCommunity.Core.Modules class ...has been renamed and moved to
IStarCommunityEntity  EPiServer.Common.IFrameworkEntity
StarCommunityEntityBase EPiServer.Common.FrameworkEntityBase
StarCommunityFactoryBase EPiServer.Common.FrameworkFactoryBase

 

StarCommunity.Core.Exceptions class ...has been renamed and moved to
StarCommunityException EPiServer.Common.Exceptions.FrameworkException

 

StarCommunity.Core class ...has been renamed and moved to
StarCommunitySystem EPiServer.Community.CommunitySystem
StarCommunityContext EPiServer.Community.CommunityContext



Migrating extensions for EPiServer Mail

The interface IMailSourceControl requires the new method void MessageSent(Message message). The purpose of this method is to allow the Mail Source Control to know when a message where the body originated from it has been sent, and to handle this in a suitable way if necessary. The Message object that is passed as a parameter is the message that was sent. You may choose to leave this method empty.

 

Merging configuration

All configuration has been moved from the separate configuration files that were used in Community 3.1, Mail 4.3 and StarSuite 2.2 to sections in web.config for Community 3.2, Mail 4.4 and Common 2.3. This means that old configuration files can not be used by the new product versions.

However, the actual settings are named the same, so migrating an existing configuration is a matter of going through the web.config generated during installation and changing the settings in the episerver.common, episerver.community and episerver.mail sections to the desired values using the old configuration files as a template.

Section episerver.community now includes the settings previously in:

Netstar\StarCommunity\AdminConfiguration.config
Netstar\StarCommunity\Modules\Chat\Chat.config
Netstar\StarCommunity\Modules\ConnectionLink\ConnectionLink.config
Netstar\StarCommunity\Modules\Contact\Contact.config
Netstar\StarCommunity\Modules\DocumentArchive\DocumentArchive.config
Netstar\StarCommunity\Modules\Expert\Expert.config
Netstar\StarCommunity\Modules\Forum\Forum.config
Netstar\StarCommunity\Modules\ImageGallery\ImageGallery.config
Netstar\StarCommunity\Modules\Moblog\Moblog.config
Netstar\StarCommunity\Modules\NML\NML.config
Netstar\StarCommunity\Modules\OnlineStatus\OnlineStatus.config
Netstar\StarCommunity\Modules\VideoGallery\VideoGallery.config
Netstar\StarCommunity\Modules\Webmail\Webmail.config

 

Section episerver.common now includes the settings previously in:

Netstar\EntityProviders.config
Netstar\Modules\Integration\Integration.config
Netstar\Modules\Replication\Replication.config

 

Section episerver.mail now includes the settings previously in:

<EPiServer UI>\Mail\EPiServerMail.config


By default the episerver.mail-section uses the configSource attribute to link to the EPiServerMail.config-file.
You can use in-line configuration directly in web.config instead of using a separate config-file.

Migrate files

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.
 
 Part of the web.config with the image gallery, document archive etc elements:

 <episerver.community>
    <sites>
      <site hostName="Default">
  ...
     <imageGallery imageAbsoluteFilePath="C:\EPiServer\VPP\MyNewSite\EPiServerCommunity\Modules\ImageGallery\Originals" thumbnailVirtualFilePath="~/EPiServerCommunity/Modules/ImageGallery/Thumbnails" imgExtension=".jpg" imgMaxWidth="640" imgMaxHeight="640" saveOriginal="true" maxUserImageQuota="0" imgQuality="100" />
  ...
  <documentArchive physicalPath="C:\EPiServer\VPP\MyNewSite\EPiServerCommunity\Modules\DocumentArchive\Files" virtualPath="/EPiServerCommunity/Modules/DocumentArchive/Files" />
        <webmail diskCachePath="C:\EPiServer\VPP\MyNewSite\EPiServerCommunity\Modules\Webmail\diskcache" defaultPasswordProviderType="EPiServer.Common.Security.CleartextPasswordProvider, EPiServer.Common.Security" />
       

Please login to comment.