administrator's guide - the sitecore developer network

Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The contents of this document are the property of Sitecore. Copyright © 2001-2012 Sitecore. All rights reserved.

Sitecore CMS 5.3 to CMS 6 Database Conversion Tool

Administrator's Guide Installation, configuration and usage guide for Sitecore CMS administrators.


of 43

Table of Contents

Chapter 1 Introduction ................................................................................................................................ 3 1.1 How the Conversion Tool Works................................................................................................... 4 1.2 Manual Conversion Tasks ............................................................................................................. 5 1.3 Limitations ..................................................................................................................................... 6

Chapter 2 Strategies for Converting Sitecore CMS 5.3 Databases to Sitecore CMS 6 ............................ 7 Chapter 3 Prerequisites ............................................................................................................................. 8 Chapter 4 Preparations .............................................................................................................................. 9

4.1 Decide Which Databases to Convert ............................................................................................ 9 4.2 Install Database Conversion Tool ............................................................................................... 10 4.3 Create Custom Security Domains ............................................................................................... 11 4.4 Copy "Security templates.xml" File ............................................................................................. 12 4.5 Copy Sitecore CMS 5.3 Databases ............................................................................................ 13 4.6 Back Up Sitecore CMS 6 Configuration Files ............................................................................. 14 4.7 Add Connection Strings .............................................................................................................. 15 4.8 Add Database Definitions ............................................................................................................ 17 4.9 Allow the dot (".") in Item Names ................................................................................................ 18 4.10 Increase httpTimeout .................................................................................................................. 19 4.11 Disable Search Indexes .............................................................................................................. 20 4.12 Upgrade Package File Name ...................................................................................................... 21

Chapter 5 Databases Upgrade Steps ...................................................................................................... 22 5.1 Select Databases ........................................................................................................................ 23 5.2 Automatic Database Conversion ................................................................................................ 25

Chapter 6 Manual Database Conversion ................................................................................................. 26 6.1 Convert Database Structure ........................................................................................................ 27 6.2 Transfer Archives ........................................................................................................................ 28 6.3 Convert Security .......................................................................................................................... 29

6.3.1 Transfer Accounts ................................................................................................................... 30 6.3.2 Convert Security Fields ........................................................................................................... 30

6.4 Update Fields .............................................................................................................................. 32 6.5 Convert Media Links ................................................................................................................... 33 6.6 Convert Masters to Branch Templates ....................................................................................... 34 6.7 Move Field Types ........................................................................................................................ 35 6.8 Move Html Editor Profiles ............................................................................................................ 37 6.9 Install Update Package ............................................................................................................... 39 6.10 Final Cleanup .............................................................................................................................. 40

Chapter 7 Clean Up Databases and Solution .......................................................................................... 41 Chapter 8 Further Conversion Steps ....................................................................................................... 43


of 43

Chapter 1

Introduction

This document describes how to use the Sitecore CMS 5.3 to CMS 6 Database Conversion Tool.

The purpose of this tool is to convert Sitecore CMS databases from version 5.3.2 rev.090212 or later to Sitecore CMS 6.4.1 Update-3.


of 43

1.1 How the Conversion Tool Works

Typically you will attach all your Sitecore CMS 5.3 databases (except for the "web" database) and run the conversion tool. The result of the conversion will be:

A "master" database that you can use with version 6.

An upgraded version 5.3 core database from which you can transfer items to the version 6 core database.

All security accounts transferred to standard .NET security database tables (typically located in the version 6 core database)

Items from version 5.3 archive and recycle bin databases moved into the new "Archive" tables in the database from which the items have been archived/deleted.


of 43

1.2 Manual Conversion Tasks

After converting the databases you need to perform some actions manually to finish the solution migration. You need to recompile your .NET code and configure any custom event handlers, pipeline steps, etc., see Chapter 8, Further Conversion Steps for details.


of 43

1.3 Limitations

The tool currently has the following limitations.

Only Microsoft SQL Server and Oracle databases are supported.

The tool converts the content of Sitecore CMS 5.3 core database and then you need to transfer one or more items (such as custom applications) into a clean Sitecore CMS 6 core database. The tool cannot upgrade a version 5.3 core database and turn it into a working version 6 database.

The tool only supports transferring users and roles that are stored as items in a standard Sitecore CMS 5.3 security databases to the new .NET membership and role tables. If you have a custom domain that stores accounts in a different database structure, you must write a custom script to transfer the users and roles to the relevant .NET tables. Alternatively, you can implement custom .NET providers to use your current database structure with version 6.

The tool does not upgrade PublishQueue. When the conversion is finished, smart or full republishing is mandatory.

Custom fields for the "Role" template are not supported in Sitecore CMS 6 since you cannot assign properties to roles in the ASP.NET 2.0 security model. The database conversion tool will not transfer values of such fields.


of 43

Chapter 2

Strategies for Converting Sitecore CMS 5.3

Databases to Sitecore CMS 6

There are at least two different strategies for converting version 5.3 databases to version 6:

1. Do a "straight conversion" where you convert the version 5.3 "master" database and use it as the "master" database for version 6.

1. "Start from scratch" where you convert the version 5.3 "master" database and then manually transfer templates, content, branches, etc. to a clean version 6 master database. Some partners even choose to manually build up the templates from scratch in version 6 and only transfer content.

Doing a "Straight Conversion"

The advantages of a "straight conversion" are:

You can use the upgraded version 5.3 master database directly with version 6.

You can focus on making your code run with version 6 instead of spending time on manually transferring items from the version 5.3 to the version 6 database.

Potential disadvantages

You might end up with more "legacy" items in the database, such as obsolete branches.

Starting from Scratch

The advantages of "starting from scratch" are:

You know that you are starting out with a completely clean version 6 database.

You will most likely end up with less "legacy" items in the database.

Potential disadvantages:

Deciding which items to transfer from the version 5.3 database to the version 6 database might be time-consuming.

You might have to transfer your data in smaller portions to avoid timeouts and/or "out of memory " errors.


of 43

Chapter 3

Prerequisites

Source installation

A Sitecore CMS 5.3 solution to be upgraded.

The solution does not need to be running

Target installation

A clean Sitecore CMS 6.X.X solution. The solution must be running.

Database Conversion Tool

You will need to download the Sitecore CMS 5.3 to CMS 6 Database Conversion Tool (and any associated downloads) from the SDN if you haven't already done so.


of 43

Chapter 4

Preparations

4.1 Decide Which Databases to Convert

Before you start the conversion, you must decide which databases you want to convert.

Normally you will want to convert the following V5.3 databases:

master

security

extranet databases

If you have made changes to the "core" database (such as adding custom applications to the start menu) and you want to transfer some of these changes, you should also convert the "core" database.

Optionally, you can convert the "archive" and "recycle bin" databases.

Important Converting the "archive" and "recycle bin" databases can take a long time if the databases contain a big number of items. We therefore recommend that you skip these databases if you are doing a test conversion of your databases in order to start upgrading your .NET code.


of 43

4.2 Install Database Conversion Tool

Download the V6DBConversionTool-XXXrevXXXXXX zip-file from the SDN.

Note It must be installed and run on the target clean Sitecore CMS 6.X.X solution.

Install the database conversion tool:

1. Start the "Installation Wizard".

2. Upload the V6DBConversionTool-1.0.0revXXXXXX.zip package.

3. Install the package.

Grant the anonymous user access to the /Website/sitecore/admin/upgrade folder (or use Windows Authentication) in order to be able to access the database conversion tool aspx page.


of 43

4.3 Create Custom Security Domains

Notice You can skip this step if the V5.3 solution is only using the "extranet" and "sitecore" domains.

In order to transfer security accounts correctly, you must create any custom domains.

This can be done using the Sitecore Desktop:

1. Log in to the Desktop of your V6 solution

2. Open the "Domain Manager" (Sitecore » Security Tools » Domain Manager)

3. Create the domain(s)

Alternatively, you can add domains by manually editing the /App_Config/Security/Domains.config.xml file.


of 43

4.4 Copy "Security templates.xml" File

You must copy the Security templates.xml file to the Sitecore CMS 6 solution to transfer security settings:

Locate the Security templates.xml file in the /sitecore/shell/ folder of the CMS 5.3 solution.

Copy the file to the /sitecore/shell/ folder of the CMS 6 solution (overwrite the existing file).


of 43

4.5 Copy Sitecore CMS 5.3 Databases

It is strongly recommended that you make a copy of the V5.3 databases and use these copies when upgrading the database content.

Apply the “Prepare for conversion to v6 script.sql” script to these copies. It will ensure that Sitecore SQL databases have the correct database schema and prevent from related errors during the database conversion process.

We recommend that you do not try to upgrade your V5.3 "web" database. Instead, perform a Full Publish after the conversion is finished to publish the upgraded master database to the V6 "web" database.

http://sdn.sitecore.net/Resources/Tools/V53_to_V6/Documentation.aspx


of 43

4.6 Back Up Sitecore CMS 6 Configuration Files

Make a copy of the following files in the clean Sitecore CMS 6 solution:

web.config

/App_Config/ConnectionString.config if you convert Microsoft SQL Server databases or /App_Config/ConnectionStringOracle.config if you convert Oracle databases.


of 43

4.7 Add Connection Strings

The purpose of this step is to make the V5.3 databases available to your V6 solution so that the conversion tool has access to the databases.

Notice that all V5.3 databases should be attached using the database names that were used in V5.3, except for the core database which must be attached as "v53_core".

If you convert Microsoft SQL Server databases, attach them by performing the following steps:

1. Open the /App_Config/ConnectionStrings.config file in the V6 solution.

2. The file should contain 3 connection strings. They could for example look like this: <add name="core" connectionString="user id=user;password=password;Data

Source=(server);Database=Sitecore_Core" />

<add name="master" connectionString="user id=user;password=password;Data

Source=(server);Database=Sitecore_Master" />

<add name="web" connectionString="user id=user;password=password;Data

Source=(server);Database=Sitecore_Web" />

3. Rename "master" to "v6_master": <add name="v6_master" connectionString="user id=user;password=password;Data

Source=(server);Database=Sitecore_Master" />

4. Add connection strings for the V5.3 databases that you want to upgrade. Each database name in the connection string must be the same it was in V5.3, except the case if you wish to upgrade data in the V5.3 core database; in this case you must attach it as "v53_core". If you are using auto attached databases, the connection strings could look like this: <add name="master" connectionString="user id=user;password=password;Data

Source=.\SQLEXPRESS;AttachDBFileName=C:\Inetpub\wwwroot\Sitecore

6.0\Databases_v53\sc53Master_Data.mdf"/>

<add name="security" connectionString="user id=user;password=password;Data


6.0\Databases_v53\sc53Security_Data.mdf" />

<add name="extranet" connectionString="user id=user;password=password;Data


6.0\Databases_v53\sc53Extranet_Data.mdf" />

<add name="v53_core" connectionString="user id=user;password=password;Data


6.0\Databases_v53\sc53Core_Data.mdf" />

<add name="recyclebin" connectionString="user id=user;password=password;Data


6.0\Databases_v53\sc53RecycleBin_Data.mdf" />

<add name="archive" connectionString="user id=user;password=password;Data


6.0\Databases_v53\sc53Archive_Data.mdf" />

If you convert Oracle databases, attach them by performing the following steps:

1. Open the /App_Config/ConnectionStringsOracle.config file in the V6 solution.

2. The file should contain 3 connection strings. They could for example look like this: <add name="core" connectionString="user id=sccore; password=sccore; Data

Source=XE" />

<add name="web" connectionString="user id=scweb;password=scweb; Data Source=XE"

/>

<add name="master" connectionString="user id=scmaster; password=scmaster; Data

Source=XE" />


of 43

3. Rename "master" to "v6_master": <add name="v6_master" connectionString="user id=scmaster; password=scmaster;

Data Source=XE" />

4. Add connection strings for the V5.3 databases that you want to upgrade. Each database name in the connection string must be the same it was in V5.3, except the case if you wish to upgrade data in the V5.3 core database; in this case you must attach it as "v53_core". If you are using auto attached databases, the connection strings could look like this:

<add name="master" connectionString="user id=sc53master;

password=sc53master; Data Source=XE" />

<add name="security" connectionString="user id=sc53security;

password=sc53security; Data Source=XE" />

<add name="extranet" connectionString="user id=sc53extranet;

password=sc53extranet;Data Source=XE" />

<add name="v53_core" connectionString="user id=sc53core; password=sc53core;

Data Source=XE" />

<add name="recyclebin" connectionString="user id=sc53recyclebin;

password=sc53 recyclebin; Data Source=XE" />

<add name="archive" connectionString="user

id=sc53archive;password=sc53archive; Data Source=XE" />

of 43

4.8 Add Database Definitions

Now that the connection strings are in place, you need to add database definitions so that Sitecore CMS knows about each database. The easiest way to do this is to use the new "include .config files" functionality in Sitecore CMS 6, which allows you to modify the configuration without changing the web.config file.

As a part of the database conversion tool, we provide a number of “include” files to make the task of adding databases easier.

Important Notice that the "db_master.config" file will temporarily change the name of the V6 "master" database to "v6_master". So for the rest of this document, we assume that "v6_master" database is the clean Sitecore CMS 6 master database, while "master" is the Sitecore CMS 5.3 master database being converted.

Perform the following steps to add the database definitions:

1. Copy files from "/sitecore/admin/upgrade/IncludeFiles" into "/App_Config/Include" (including the ItemNameValidation.config file which is explained in Section 4.9, Allow the dot (".") in Item Names).

2. By default, these include files will add database definitions for the following databases:

a. master

b. security

c. extranet

3. If you want to upgrade the contents of the V5.3 core database or migrate data from the archive or the recycle bin database, rename the appropriate "db_*.config.disabled" files to "db_*.config".

a. For example, rename "db_recyclebin.config.disabled" to "db_recyclebin.config" if you want to migrate data from the V5.3 recycle bin database.

4. If you have any custom V5.3 databases that you want to convert, you must create an include file for each database.

a. Copy one of the existing include files (for example "db_security.config" if you want to convert a custom security database)

b. Open the include file and locate the following line: <database id="security" singleInstance="true" ...>

c. Change the database id to the name of your custom database, for example: <database id="intranet" singleInstance="true" ...>

d. Important: If you have made a copy of "db_master.config", you must remove the following lines from the top of the file for you custom database definitions: 

<database id="master">

<patch:attribute name="id">v6_master</patch:attribute>

</database>

5. Optionally log in to the Sitecore CMS 6 desktop (default login credentials: login: Admin, password: b) to verify that you can see the databases.

a. Notice however that trying to see data in any of the V5.3 databases might not work, since their database structure has not been updated yet.


of 43

4.9 Allow the dot (".") in Item Names

In Sitecore CMS 6, the default value for the "ItemNameValidation" has been changed so that it is no longer possible to create items with the dot characters (".") in item names.

Many Sitecore CMS 5.3 solutions have item names with dots, so we provide an include file that changes the ItemNameValidation setting to "^[\w\*\$][\w\s\-\$\.]*$" which will allow item names with dots.

If you do not need this functionality, feel free to remove this include file or rename it to ItemNameValidation.disabled.

Note If you provide a custom pattern for the ItemNameValidation setting, insert this pattern into the include file (or remove the file), since the include file overrides the value that is specified in the web.config file.


of 43

4.10 Increase httpTimeout

By default ASP.NET has a 10 minute response timeout. For some operations, for example archive conversion, this time is not enough.

When installing the Update Package Installation Wizard, a Web.config file which increases the timeout to 170 minutes is installed into the /sitecore/admin folder. If that time is still not enough, change the following setting in the /sitecore/admin/Web.config file:

<httpRuntime maxRequestLength="1638400" executionTimeout="21600" />


of 43

4.11 Disable Search Indexes

There are two reasons to turn the searching functionality off:

Optimization purpose

Sitecore CMS 6.0 does not support Oracle databases from version 5.3

To disable search indexes, special configuration file is provided which is located by the following path: “sitecore\admin\upgrade\IncludeFiles\DisableSearch.config”. Copy this file into App_Config\Include folder and restart Sitecore application to make configuration settings work.

If this recommendation was skipped, you would observe an exception like “ORA-00942: table or view does not exist” right after starting of Sitecore application with version 5.3 Oracle databases attached.


of 43

4.12 Upgrade Package File Name

Upgrade package, which provided with the database conversion tool, could have different names depending on the target version of Sitecore CMS 6 it is going to be used for.

Configuration file “\sitecore\admin\upgrade\IncludeFiles\UpgradePackageFileName.config” is provided with the database conversion tool and must be copied into “App_Config\Include” folder before starting a conversion process.

Unless you properly copied configuration file you would see “file not found” exception during the Install Update Package step.


of 43

Chapter 5

Databases Upgrade Steps

The database conversion from V5.3 to V6 is performed with the help of a series of aspx pages.

You get access to these aspx pages by opening the following URL:

/sitecore/admin/upgrade/Main.aspx


of 43

5.1 Select Databases

This step allows you to select which databases to convert. The choices you make on this page determine which databases will be converted in the subsequent steps.

The conversion tool recognizes the standard V5.3 database names, and will make appropriate selections automatically (database type and domain/archive name).

Usage Guide

1. Verify that all databases that you want to convert are listed on the page.

2. Make sure you put checkmarks only next to the databases that you want to convert.

3. Select the relevant database type for each database.

a. "Content" is used for content databases (master, core, custom content databases).

b. "Security" is used for security databases.

c. "Archive/recycle bin" is used for archive databases, including the Recycle Bin.

4. For all security databases, make sure that the correct V6 domain is selected. The users and roles will be transferred to this domain.


of 43

5. For all archive databases, make sure that the correct archive is selected in the Archive name field.

By default, all conversion steps will be performed automatically. This is the recommended conversion mode. If you want to perform a step-by-step manual conversion, select the relevant radio button in the conversion mode section.


of 43

5.2 Automatic Database Conversion

This page will convert the selected Sitecore CMS 5.3 databases so that they can be used with Sitecore CMS 6.

Important It is strongly recommended to read the "Manual Database Conversion" chapter for a description of each step. Pay special attention to the sections marked with "Notice:" and "Important".

Usage Guide

1. Click "Start conversion".

2. A report with the status of all the executed conversion steps will be displayed in the right-hand side of the page.

3. When the conversion has been completed, you should review the report for information about conversion errors and warnings.


of 43

Chapter 6

Manual Database Conversion

When performing a manual conversion, you will be presented with a list of the conversion steps:

Always run the conversion steps in the order that they are listed on the Manual Database Conversion page.


of 43

6.1 Convert Database Structure

This page will perform the following actions on the V5.3 databases:

Convert database tables to new schema

Convert "blob" values (binary objects are stored differently in the database in V6)

Convert proxy definitions (the proxy type is stored differently in the database in V6)

Usage Guide:

Click "Convert" to start the database conversion.

Status for the database conversion will be displayed in the right-hand side of the window.

o Please wait until this frame has fully loaded before returning to the Main Page.


of 43

6.2 Transfer Archives

In Sitecore CMS 5.3, items in the Archive and the Recycle Bin databases are serialized and stored as an XML chunk. In Sitecore CMS 6, the archived items and fields are stored in 3 database tables (Archive, ArchivedItems, ArchivedFields).

This page will deserialize the information in the V5.3 archive databases and store it in the new format.

Important Converting the "archive" and "recycle bin" databases can take a long time if the databases contain a big number of items. We therefore recommend that you skip this step if you are doing a test conversion of your databases in order to start upgrading your .NET code.

Usage Guide:

Click "Process" to start the operation.


of 43

6.3 Convert Security

In Sitecore CMS 5.3, users and roles were stored as items in a Sitecore database. In version 6, users and roles are by default stored in standard ASP.NET 2.0 Membership and Role tables (depending on the provider configuration in the web.config file).

In version 6, all users and roles are stored in the same database tables, not in different databases for each domain. Therefore, users and roles will now have their domain as a prefix. For example, the user named "Anonymous" in the "extranet" domain will now have the username "extranet\Anonymous".

TIP By default, Sitecore CMS 6 will use the Membership and Role tables in the "core" database. If you wish, you can configure Sitecore to use a separate database for storing users and roles by changing the relevant connection strings for the security providers in the web.config file.

Notice The Convert Security page can only transfer security accounts and role assignments from standard V5.3 databases where users and roles are stored as Sitecore items. If you have a custom domain that stores accounts in a different database structure, you must write a custom script to transfer users and roles to the relevant .NET tables. Alternatively, you can implement custom .NET providers to use your current database structure with V6.

The "Convert Security" page consists of two different steps:


of 43

6.3.1 Transfer Accounts

This step will create users and roles using the ASP.NET Membership and Role providers. The domain of the users and roles will be added to their V5.3 username to make the domain association work correctly in V6.

Users in the "sitecore" domain will automatically be added as members of the "Sitecore Client Users" role, otherwise they would no longer be able to log into the Sitecore clients (Desktop, Page Editor, etc.).

Important Notes Existing users (such as "sitecore\Admin") will be updated to match the information in the Sitecore CMS 5.3 database. All properties (for example name, email and password) will be overwritten, and the role assignments will be updated.

By default, blank passwords are not supported in Sitecore CMS 6. If one or more users have a blank password, their password will be changed to their username in version 6. This includes the "sitecore\Admin" user, so if the Admin user had a blank password in Sitecore CMS 5.3, you must use "Admin" as the password after the conversion.

During the conversion, the "extranet\Guest" role will be renamed to "extranet\Guests" to avoid confusion with the "extranet\Guest" user.

Usage Guide:


Information about the added user/roles and their assignments will be output on the page.

6.3.2 Convert Security Fields

In Sitecore CMS 6, security assignments are stored in a new format that supports the creation of custom access rights. As a consequence of this change, field security assignments are now stored in


of 43

the standard "__Security" field and the special "Field Security" field in template fields has been obsolete.

This step will update the assignments stored in the "__Security" field to use the new format (including moving assignments in the "Field Security" to the "__Security" field).

Notice This page will not upgrade custom security fields. We recommend that you write a custom upgrade script to upgrade such fields and that you use custom access rights in V6 for this purpose.

Usage Guide:

Click "Process" to start the operation

Information about the conversion will be output on the page.

o For assigned access rights in the security field, only warnings and errors will be output. These warnings will typically just mean that some rights have been assigned to a user/role that no longer exists.

o For "Field Security", a list of all template fields with assigned field security permissions will be output.

Notice If access rights have been assigned to a user or role that doesn't exist in the security database, the access rights for this account will still be converted. In this case, a special format will be used for the account name (using a prefix + the domain name + the GUID of the account). Example: unknown: sitecore\{9D305E97-6E64-4AAD-8BB7-5D7ADAFAA8FB}

In most cases, such assignments are only useful during the conversion, where they can be used to do troubleshooting in relation to missing accounts. The assignments can be removed automatically after conversion as part of the "Final Cleanup" step.


of 43

6.4 Update Fields

This step will convert the following fields:

"Layout" fields.

o The 'uid' attribute will be added to the XML of all layout fields.

Fields that store references to masters.

o Some masters that existed in V5.3 have been removed in V6, since it is now possible to insert items directly from templates.

o References to the obsolete masters in the "Master" fields will be removed.

o Also, the "Masters" field (now called "Insert Options") will be updated so that references to the obsolete masters are changed to point to the relevant templates.

"Source" fields for html profiles. The names of some of the standard profiles have been changed, and will therefore be updated:

o Rich Text Default » Rich Text Medium

o Default » Rich Text Medium

o Full » Rich Text Full

Notice Since Sitecore CMS V6 no longer support Cute Editor, the standard V5.3 html editor profiles "Default" and "Full" no longer exist in V6. References to these profiles will be changed to "Rich Text Medium" and "Rich Text Full" as described above.

Usage Guide:


Information about the conversion will be displayed on the page:


of 43

6.5 Convert Media Links

In Sitecore CMS 6, links to media items are stored in a new format that allows the CMS to dynamically generate appropriate URLs to media based on the current site, language, etc.

The new format uses the GUID (in the form of a 'short' GUID) when inserting links in the HTML. For example: <a href="~/media/BE9E50F7F9DC4C4687BBEDE567BCA2AA.ashx">Download

PDF</a>

The link will be expanded to a 'normal' link with the path to the resources on the published website.

To make this work correctly, existing links must be converted to the new format.

Usage Guide:


Information about the conversion will be displayed on the page, including any warnings about links that could not be converted to the new format (most likely because the item being linked to does not exist):

Notice After completing all the database conversion steps, you can use the "Broken Link Report" in Sitecore CMS to get information about the items and fields that contain references to media items.


of 43

6.6 Convert Masters to Branch Templates

In Sitecore CMS V6, the branch template replaces the concept of a master.

Existing masters will be converted to branches with a single sub-item for backwards compatibility.

Notice Executing this step will take some time (several minutes) to complete, depending on the number of masters to be converted.

Usage Guide:

Click "Process" to start the operation

Information about the conversion will be displayed on the page:

You might get error messages during the conversion, for example if a master exists but the template it is based on has been deleted.


of 43

6.7 Move Field Types

In Sitecore CMS 6, the definitions of supported field types have been moved to the "core" database.

This step will move custom field types from any content databases (typically the V5.3 master and core database) to the V6 core database. Also, if you have made custom changes to any of the standard Sitecore field types, these changes will be copied to the V6 core database.

Notice If you have added custom fields to the "Template Field" template, these fields will be automatically transferred to the core database.

The field type definitions in the V5.3 content databases will automatically be removed from the selected databases after being moved to the core database.


of 43

Usage Guide:


Information about the field types that have been moved to or updated in the V6 core database will be displayed on the page.

If you have changed the definition of a field type in more than one database (for example both in the "master" and "v53_core" database), an error message will be output. Such conflicts must be resolved manually.


of 43

6.8 Move Html Editor Profiles

In Sitecore CMS 6, the definitions of Html Editor Profiles have been moved to the "core" database.

Important This page will overwrite the Html Editor Profiles in the "core" database. If you process multiple databases, you may lose data! We therefore recommend that you only process the "master" database. If you have custom Html Editor Profiles defined in the V5.3 core database, we recommend that you manually transfer them to the V6 core database.

Notice CuteEditor is no longer supported as rich text editor in V6. The default CuteEditor profiles named "Default" and "Full" will therefore not be moved to the core database.


of 43

Usage Guide:

Make sure that the "master" database is selected.

Click "Process" to start the operation. It can take several minutes, so please be patient.

Notice: If you have other content databases with custom Html Profiles, you can select them as well, but these profiles will overwrite any already transferred profiles. We therefore recommend that you manually transfer any additional profiles to the V6 core database.

Information about the field types that have been moved to or updated in the V6 core database will be displayed on the page.


of 43

6.9 Install Update Package

The purpose of this step is to make the standard Sitecore CMS 5.3 items in the master database match the standard items in a clean V6 database. The package will make required changes to system templates, remove unneeded masters, etc.

We recommend that you make a backup of your upgraded master database at this point, since the Update Package will make changes to the system templates. This means that you could potentially lose data if something does not work as expected when installing the package on your solution.

If the Master database has not been selected on the Select Databases step, then you just skip Install Update Package step (the Install Package button is disabled).

To install Update Package, check master check box and click Install Package.

After the installation is complete, you will be presented with a report of errors, conflicts and warnings (most likely a similar number as in the previous step), but often you will see more collisions due to items having been moved compared to V5.3).

If you wish, you can review the installation log file (/data/logs/upgrade.YYYYMMdddd.txt) or you can export the report to XML file. When you are done, close the browser window to go back to the Main Page

After completing this step, your V5.3 master database will be upgraded to work as a Sitecore CMS 6 master database.

If you see “file not found” exception during the installation of the package, check if you have properly copied configuration file with the name of the upgrade package, see the Upgrade Package File Name section for details.


of 43

6.10 Final Cleanup

This page helps you to clean up your database after the conversion from Sitecore CMS 5.3 to CMS 6.

Masters

This step will remove references to all non-existent masters/branches (both system masters and custom masters). If you do not perform this step and try to save an item that refers to a non-existent master, you'll get a "broken link" warning.

Usage Guide:

Click "Cleanup masters" to start the process. This can take a while, so please be patient.

The results will be displayed in the right-hand side of the window.

Security

When converting security fields (as a part of the "Convert Security" step), the conversion tool often encounters access rights that have been assigned to a user or a role that does not exist in the V5.3 security databases. A special format is used for such account names (a prefix + the domain name + the GUID of the account). Example:

unknown: sitecore\{9D305E97-6E64-4AAD-8BB7-5D7ADAFAA8FB}

This step will remove all references to such security accounts that could not be resolved during the conversion of the security fields.

Usage Guide:

Click "Cleanup security" to start the process. This can take a while, so please be patient.

The results will be displayed in the right-hand side of the window.


of 43

Chapter 7

Clean Up Databases and Solution

Database Cleanup

Perform the following steps to clean up the databases:

Rebuild link database.

Rebuild search indexes.

Republish to web database (use smart or full publishing mode).

Solution Cleanup

Perform the following steps to clean up your solution after the conversion.

Remove include files (db_*.config) from the "/App_Config/Include" folder (or rename them to *.disabled).

o This will remove database definitions for V5.3 databases.

o You might want to leave "db_v53_core.config" in place, so that you still have access to items in the upgraded V5.3 core database.

Remove “/App_Config/Include/DisableSearch.config”.

Remove “/App_Config/Include/UpgradePackageFileName.config”.

Change "/App_Config/ConnectionStrings.config" if you converted Microsoft SQL Server databases or "/App_Config/ConnectionStringsOracle.config" if you converted Oracle databases.

o Remove connection strings for the unneeded V5.3 databases (as well as the V6 master database).

o v6_master (optional – you might keep it for reference)

o security

o extranet

o v53_core (optional)

o recyclebin

o archive

Restore the web.config file.

Remove conversion tool folders.

o /sitecore/admin/upgrade (including sub folders).

o /sitecore/admin/packages ( only the V6DBConversionTool-XXXrevXXXXXX.zip-file)


of 43

Remove conversion tool files

o /bin/Sitecore.V6DBConversion.dll

Optionally detach the databases that you no longer need from the database server and delete the database files:

o security

o extranet

o archive

o recyclebin

o any custom security/archive databases


of 43

Chapter 8

Further Conversion Steps

Your databases have now been upgraded for Sitecore CMS 6.

Typically you will now want to perform the following steps:

Copy files from V5.3 solution to V6 solution

o Layouts

o XSLT files

o CSS files

o Media library files stored on disk (as specified by the "Media.FileFolder" setting, typically "/App_Data/MediaFiles")

o Other Images and graphics

o Etc.

Make the custom code in your .NET project(s) compile against Sitecore CMS 6.

Note The upgrade procedure described in this document focuses on upgrading the data in your Sitecore solution. This document does not discuss code-related changes that will be required in most solutions that use .NET code in Sublayouts or Web Controls. Developers should upgrade their .NET code to use the FieldRenderer class as well as dynamic linking features.

Add any event handlers, pipeline steps, etc. HINT: Consider using "include files" for this.

Transfer items from the upgraded V5.3 core database to the V6 core database.

administrator's guide - the sitecore developer network

Documents