Migrate EPiServer Relate+ 1 to EPiServer Relate+ 2

 

Preconditions

This document is actually a description of a specific migration project, but written in a more general way so that it can be used as an overview of the migration work for other sites. Several steps refers to other documentation, it is a highly recommended to read these documents carefully during the migration. The migrated site in this case was in most aspects a standard installation of the old Relate+ package. Changes were mostly made to the design except for major changes in clubs and an added special member area. The time frame for a project like this depends of the extent and complexity of custom made functionality in the solution.

Overview

Start

The starting point is a website built on EPiServer Relate+ 1.0 SP1, EPiServer CMS 5 R2 and EPiServer Community 3.2 SP1. Both CMS and Community use the same database.

 

Goal

Our goal is to run a Relate+ 2 site with the same functions and appearance as the original website. The aim is also to run the site on two separate databases, one for the CMS data and one for the Community data, to make future upgrades easier.

 

Create the start conditions

Before starting the migration, some start conditions needs to be created in order to get a suitable environment to work with.

1.      Upgrade the website to EPiServer CMS 6

Upgrade the website to EPiServer CMS 6. Use the Deployment Center for the upgrade. Note that a new license file needs to be added for the site to function after the upgrade (The w3wp process might stop work without a new CMS 6 license).

2.      Install a new Relate+ 2 site

Open Deployment Center and install a new complete Relate+ 2 site including a new database. This installs a product package for EPiServer CMS 6 with EPiServer Community 4 and EPiServer Mail 5 along with a sample website. We will later migrate code and data from our old site into this new site. The new site will be used as target for migration of the code and the new database will be used as target for the migration of the community data. The CMS part of our data is in this stage already in version 6 of EPiServer CMS so we will use the original database for this, which means that CMS part of the new database will not be used.

Note that the new database needs to be completely untouched after the installation. This means for example that you cannot login to the site. If you do login to the site data will be stored which causes the script to stop.

Note also that if you have to run the application pool as a specific user identity, now setup this in the IIS for the new site.

 

Migrate data

To be able to use our Relate data in the new Relate+ 2 site it needs to be migrated.

1.      Run the migrate script

Run the SQL script “Migrating from EPiServer Mail 4.4 to EPiServer Mail 5.0 and EPiServer Community 3.2 to EPiServer Community 4.0” to migrate data. There are some settings to be done in this script depending on the setup. Read and follow the separate instructions for the script carefully to get the settings right. Use the original database as source database and the new Relate+ 2 database as target database. This script makes no changes to the source database, but it is always a good idea to make sure you have new backup available just in case.

2.      Use our new databases

Now the community data is transferred and migrated into the database of our new website. But the database still contains CMS data for the sample site. In order to use CMS data from our original site we need to point out our original database as the CMS database for the new site.

Open up the file connectionstrings.config and enter paths and other settings for the databases:

  • EPiServerDB: Setup the original database for CMS data in the new Relate+ 2 website.
  • EpiServerCommon: No changes are needed here as the migration script inserted our community data into the new Relate database.

3.      Re-index community data

The new search function is added in Relate+ 2 and is optional to use in the new site. A special search index is used by the search function. Normally this index is updated by the index service, but in this stage we need to populate it with an index of the migrated data. A separate tool, ReindexRelatePlus2.aspx, is included with the migration script that will queue existing entities for indexing. Follow the separate instructions for this tool. Also take a look at the section “Index service settings” later in this article.

 

Migrate code

Now the site is using databases that contain data in proper format. CMS data is in version CMS 6 and Relate data is in version Relate+ 2. Next step is to create code that can handle and display this data correctly.

1.      Move and fix code for CMS

The new Relate+ 2 site contains standard EPiServer CMS templates for the Relate+ 2 package but we are running it with our data which probably contains other page types that requires other templates and functions. Work through the framework, page types, property types, functions, settings, language files and so on and transfer the code to the new website. Make sure it compiles and works as intended.

2.      Move and fix code for Relate+ 2

Like in the previous step code for the Relate+ part needs to be converted to support the new version and moved into the new site. The goal is to give the new website the same design and functions as the original site but running in the new version. All code in the original project that extends the code of the standard installation needs to be reviewed and moved. Work through the code carefully, there are many breaking changes in the Community core. Alter the code until it compiles and run as intended in the new environment. Read the document describing the changes thoroughly as it will help you a lot during this work. The most efficient approach in this process may vary within the project depending on how each part is written. But a suggestion is not to copy and paste complete files; instead make changes to the templates as you go.

3.      Insert new Relate+ 2 functions

There are new features in Relate+ 2 that did not exist in earlier versions, such as search. Of course it is optional to include these new functions into your site. To add the search functionality you need to create new search page types in admin mode and publish pages in the page tree to access the search function. An easy way of doing this is to export the published pages for search from the standard templates in the Relate+ 2 installation and import them into the new site along with the page types. You can also take the quick search functionality from the standard templates and add it to your site. Then adjust these functions so they get your sites look and feel.

The search functionality depends on a special index. Read more about this in the sections “Re-index community data” and “Index service settings” in this document.

 

Test and cleanup

Now the migration is finished. Test everything thoroughly and remove the parts of the databases which no longer are used.

1.      Browse through the website and test all functions

Every page type and function should now be tested to make sure everything works as expected in the new environment.

2.      Clear the original database from Relate tables

The new setup only uses the EPiServer CMS part in the original database; the Relate+ part is read from the new database. However the old tables for Relate+ are still in the original database. This does not matter actually but since they are not used it is favorably to remove them. In the migration package a script “Drop Relate tables” is included, follow the separate instructions and run the script to remove the tables from the database.

3.      Clear the new database from CMS tables

The new setup only uses Relate+ part in the new Relate+ 2 database; the EPiServer CMS part is read from the original database. However the tables for CMS are still in the new database. This does not matter actually but since they are not used it is favorably to remove them. At this point there is no script available to remove the CMS tables from the database, leaving the option of manual removal. This is however a tedious operation since it is necessary to remove the tables in a specific order. So you will probably just let them be there unused.

 

Good to know

Depending on the environment, some adjustments might be needed.

1.      Group names

The default group name for community members group is ”CommunityMembers”. If you use some other name of this group in your solution you need to make changes in the file “CommunitySecurityModule.cs” located in “RelatePlus/CommunityModules”.

Default this line is used to get the group:

IGroup communityMembersGroup = SecurityHandler.Instance.GetGroupByName("CommunityMembers");

Instead, declare a local variable:

const string GROUPNAME = "YOURGROUPNAME";

And use this to get the group:

IGroup communityMembersGroup = SecurityHandler.Instance.GetGroupByName(GROUPNAME);

If you use other group names than default you might also need to take a look at the location section in web.config so the correct groups is allowed to get into EPiServerCommunity: 

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

2.      Group mapping

When installing the default Relate+ 2 package, the group “CommunityMembers” is used and given the intGroupID = 2. If you want to use some other group to act as the CommunityMembers group (for example when using an AD with groups) you need to map this custom group to the CommunityMembers group. Execute the following query on the database with your group id; in this example our custom group id is 213.

UPDATE
[dbMyRelateSite].[dbo].[tblEPiServerCommonEntityGroupAccessRights]
SET intGroupID=213
WHERE intGroupID=2

To find the group id of your group look in the table “tblEPiServerCommonGroup”:

SELECT intID
FROM [dbMyRelateSite].[dbo].[tblEPiServerCommonGroup]
WHERE strName='YOUR_GROUP_NAME'

3.  Index service settings

To get index service to work properly you may have to change its “baseUri”. Also make sure that it is located on the same machine that is about to get indexed.

<episerver.search active="true">
  <namedIndexingServices defaultService="localIndexingService">
    <services>
      <!--<add baseUri="{indexingServiceBaseUri}" accessKey="{accessKey}"/>-->
      <add baseUri="http://PATH_TO_YOUR_SITE/IndexingService/IndexingService.svc" accessKey="local" />
    </services>
  </namedIndexingServices>
  <searchResultFilter defaultInclude="true">
    <providers />
  </searchResultFilter>
</episerver.search>

4.  Image upload in blogs

The image upload function in blogs needs some scripts to be included in the code. Normally you include your scripts in the end of the MasterPage but this function needs them to be included earlier in the code. So, one way of fixing this is to include the following lines in imagebrowser.aspx:

<script src="http://www.google.com/jsapi"></script>
<script>
  // You may specify partial version numbers, such as "1" or "1.3",
  //  with the same result. Doing so will automatically load the
  //  latest version matching that partial revision pattern
  //  (e.g. 1.3 would load 1.3.2 today and 1 would load 1.4.2).
  google.load("jquery", "1.4.2");
  google.load("jqueryui", "1.8.4");
  google.setOnLoadCallback(function() {
    // click on the image in ImageGallery, close the ImageGallery dialog and return selected image to TinyMCE textbox
    $("a.imageAnchor").click(function(event) {
      selectPhoto($(this));
      return false;
    });
  });
</script>