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.

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:

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:

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

Next up is the StarSuite.Core namespace:

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

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

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.

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

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:

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

Some of the classes in StarCommunity has changed name completely:

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:

Section episerver.common now includes the settings previously in:

Section episerver.mail now includes the settings previously in:

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

Comments