Try our conversational search powered by Generative AI!
AI OnAI Off
| Views: | 13551 |
| Number of votes: | 6 |
| Average rating: |
Migrate EPiServer Relate+ 1 to EPiServer Relate+ 2
Sep 29, 2010
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.
To follow the instructions in this article you need to download the migration package that contains the SQL scripts and the ReIndex tool.
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.
Note that before running the re-index process any existing index needs to be removed. Check the web.config file and go to the section where “directoryPath” for the index is set:
<episerver.search.indexingservice>
<namedIndexes defaultIndex="default">
<indexes>
<add name="default" directoryPath="C:\EPiServer\VPP\MyRelate2Site\Index" />
</indexes>
</namedIndexes>
</episerver.search.indexingservice>
In this folder two subfolders “Main” and “Ref” is automatically created. To clear the index: stop the site, remove these two folders, then start the site and browse the site and perform a search query. This will recreate the folders and files needed for the re-index process. Now run the ReindexRelatePlus2 tool.
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 accessKey="local"
baseUri=http://PATH_TO_YOUR_SITE/IndexingService/IndexingService.svc />
</services>
</namedIndexingServices>
<searchResultFilter defaultInclude="true">
<providers />
</searchResultFilter>
</episerver.search>
4. WCF Error: This collection already contains an address with scheme http
Windows Communication Foundation (WCF) is used in Relate+ 2. If the site is using more than one binding the error “WCF Error: This collection already contains an address with scheme http” will appear. Default setup in web.config is configured for only one binding:
<system.serviceModel>
<serviceHostingEnvironment aspNetCompatibilityEnabled="true" />
</system.serviceModel>
To add support for more bindings (for example http://www.mysite.se and http://www.mysite.com) add baseAddressPrefixFilters:
<system.serviceModel>
<serviceHostingEnvironment aspNetCompatibilityEnabled="true">
<baseAddressPrefixFilters>
<add prefix="http://www.mysite.se"/>
<add prefix="http://www.mysite.com"/>
</baseAddressPrefixFilters>
</serviceHostingEnvironment>
</system.serviceModel>
For more information about service hosting environment and WCF take a look at for example these links:
- http://stackoverflow.com/questions/561823/wcf-error-this-collection-already-contains-an-address-with-scheme-http
- http://msdn.microsoft.com/en-us/library/ms731336(v=VS.90).aspx
- http://msdn.microsoft.com/en-us/library/ms731082.aspx
5. 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>
Comments
Please login to comment.
Very nice work Klas!
Perfect - just what I was looking for.
Great post has become very important after 2 months away from epi :)
Hi Klas,
Its a nice Article.
We need some help for reindexing the community entities.
We have tried to recreate the index using reindexrelateplus2.aspx, it was recreating index for some entities and stops after some time. it is neither showining any error nor the 'Done' message specified in the page. We have increased the timeout but still no change in the behaviour.
So we have updated the code and pass individual types to re-create index. it is working for Club, Blog, Images and forum reply but As soon as we pass the type of 'EPiServer.Community.DocumentArchive.Content' or 'EPiServer.Community.DocumentArchive.Document' or 'EPiServer.Community.Forum.Topic' some time it shows the below error and some time stops without showing any message -
Error:
2011-01-31 07:11:20,887 ERROR [7] EPiServer.Search.IndexingService.IndexingServiceHandler.UpdateReference - Could not find main document with id: 'c3d267d8-5a63-4fec-b710-8cc8a1657c33' for referencing item id '65fd6196-e3a8-4b7d-93c7-f4e943fb08ac'. Continuing anyway, index will heal when main document is added/updated.
2011-01-31 07:11:21,403 ERROR [7] EPiServer.Search.IndexingService.IndexingServiceHandler.UpdateReference - Could not find main document with id: 'c3d267d8-5a63-4fec-b710-8cc8a1657c33' for referencing item id 'a875beec-5a5f-4758-a8d3-9d4c97931e2f'. Continuing anyway, index will heal when main document is added/updated.
…
We checked these Guids in tblEPiServerCommonEntityGuid table, it belongs to type Topic and Reply.
The hierarchy for the Reply -> Topic -> ForumRoom ->Forum is exists in the system for the above Reply.
Could you please help us to resolve this issue?
By default the role provider is episerver common.
If any changes are there need to be mentioned as per old web.config.
Note:Windows role provider and Sql role provider will not work for episerver community.
The given key was not present in the dictionary. This is the error when i try to search. Can any one help.
Ah, I found out that
had the defaultService value empty and that caused the error.