Print

Data Migration module consists of two packages:

• Migration Wizard package.
   
• Migration Service package.

These packages are distributed as a standard Sitecore packages; hence in order to start using them, you should install the packages. Please, refer to the Installing Modules and Packages article if you are not familiar with the Sitecore standard Packager tool.

1.  Migration Wizard Package

This package is installed on the target Sitecore installation. It allows the user to control and fine tune the migration process.Choose the appropriate version of the Migration Wizard according to the version of the target Sitecore solution (the Sitecore installation where you are going to migrate the data to).

Install the package and then modify your web.config file:

1. Register the new message handler for the migration wizard. Add the following line to the <messages> section:
   • Sitecore 5.2.X and earlier:

     <message name="datatransfer:run" type="Sitecore.Modules.Migrate.UI.MessageHandler,Sitecore.MigrationWizard" method="Run"/>

   • Sitecore 5.3:

     Open /App_Config/commands.config file and add the following command under <configuration...> definition:

     <command name="datatransfer:run" type="Sitecore.Modules.Migrate.UI.MessageHandler,Sitecore.MigrationWizard"/>

2. Include module configuration in the web.config file:

   Sitecore 5.3

   <sitecore database=...>
   <!-- ADD THE LINE BELOW -->
       <sc.include file="/App_Config/MigrationModule.config" />
        <sc.variable name="dataFolder" value="/data" />
       <sc.variable name="mediaFolder" value="/upload" />
       <sc.variable name="tempFolder" value="/temp" />
   ...
   </sitecore>

   Sitecore 5.2 and earlier
   Add the lines given below to the ‘/configuration/sitecore’ section:

      <migration>

         <mapping> 

        <!-- Sitecore Media library Images folder from 4 -->

            <add sourceID="{EB8EAEEE-00F5-4861-BC15-330AA0040156}" targetID="{15451229-7534-44EF-815D-D93D6170BFCB}"/> 

        <!-- Sitecore Users folder from 4 -->

            <add sourceID="{EE9CC8CA-34F9-4610-A433-460B8D0A840D}" targetID="{73C32316-C412-4D57-A48D-D0EC9EE2F96E}"/>

        <!-- Sitecore Groups folder from 4 -->

            <add sourceID="{6F349757-73DE-4B73-8C8E-B17E96C0B197}" targetID="{AAFA5E5A-3F75-4C70-B39C-D2E97A11D74D}"/>

        <!-- Extranet Users folder from 4 -->

            <add sourceID="{F4F847B2-57C1-4CBD-A1B4-45131B42922E}" targetID="{73C32316-C412-4D57-A48D-D0EC9EE2F96E}"/>

        <!-- Extranet Groups folder from 4 -->

            <add sourceID="{6F349757-73DE-4B73-8C8E-B17E96C0B197}" targetID="{AAFA5E5A-3F75-4C70-B39C-D2E97A11D74D}"/> 

        <!-- Sitecore Admin user -->

            <add sourceID="{C71338BB-09C1-4D0E-B10E-51553123F842}" targetID="{D152CB5F-7E8F-40A9-A017-29F0FCF15745}"/>               

        <!-- Sitecore Everyone role -->

            <add sourceID="{A0607F3E-7214-4440-BB87-4C6FDC6AB948}" targetID="{00088163-665D-4F6F-9E63-C0CF1FB4E2FE}"/>               

        <!-- Extranet Everyone role -->

            <add sourceID="{3B7BB5B7-2E92-49B5-A085-5A4FF8EEC528}" targetID="{00088163-665D-4F6F-9E63-C0CF1FB4E2FE}"/>      

           <!-- GIF template to unversioned Image template -->

            <add sourceID="{27F12339-1571-482B-B39D-B03004CCF2AD}" targetID="{C97BA923-8009-4858-BDD5-D8BE5FCCECF7}"/>

            <!-- Path field -->

            <add sourceID="{ABD37B99-FAF4-449B-854F-82C0DAF73B3D}" targetID="{B48AF244-B099-44CE-B8B9-3D3C14194C06}"/>

            <!-- Alt field -->

            <add sourceID="{D7F6DFE2-151F-4023-8A4A-8D7FE202C39D}" targetID="{8CF45D0E-ADD4-4772-911A-AC6FC50F9C7D}"/>

            <!-- Description field -->

            <add sourceID="{94478368-C3C2-45CC-8D27-C877B416DF14}" targetID="{240432D4-3604-46B1-A0F5-78ABC6766486}"/>

            <!-- Title field -->

            <add sourceID="{C17E1045-188C-46F6-B3FD-3997809BEA1A}" targetID="{DC34A2CA-4E0A-4640-B375-62B79F67AFF8}"/>

            <!-- Vertical resolution field mapped to the vertical resolution of the image field -->

            <add sourceID="{E14071A1-3D5D-491C-9A6E-37A66429B44C}" targetID="{337274F2-2E48-41B1-B0B8-56C7D5F7C813}"/>

            <!-- Horizontal resolution field is mapped to the horizontal resolution of the image field -->

            <add sourceID="{D572FD07-28E2-4083-BC47-607496F86EDA}" targetID="{48A65837-49E3-42EE-91ED-75056DAE12D5}"/>

            <!-- BitDepth field is mapped to the BitDepth of the image field -->

            <add sourceID="{5A57AB2A-2629-49F4-A612-63850217C291}" targetID="{A20F4915-90D5-4070-A051-5F7AAB4DDB24}"/> 

         <!-- JPG template to unversioned Image template -->

            <add sourceID="{2EE734A4-D085-45D1-B924-66F799CC8D2C}" targetID="{C97BA923-8009-4858-BDD5-D8BE5FCCECF7}"/>

            <!-- Path field -->

            <add sourceID="{05193A2D-F4EB-463C-891A-97C2CB3D84FB}" targetID="{B48AF244-B099-44CE-B8B9-3D3C14194C06}"/>

            <!-- Alt field -->

            <add sourceID="{380E074F-A4AE-451B-B1CA-A6E8B3DB479A}" targetID="{8CF45D0E-ADD4-4772-911A-AC6FC50F9C7D}"/>

            <!-- Description field -->

            <add sourceID="{2A9F5FCB-88F1-4EC8-B4E6-F8DF6D527CB5}" targetID="{240432D4-3604-46B1-A0F5-78ABC6766486}"/>

            <!-- Title field -->

            <add sourceID="{DC065C5F-53DF-4525-853C-A1D888B25431}" targetID="{DC34A2CA-4E0A-4640-B375-62B79F67AFF8}"/>

            <!-- Vertical resolution field mapped to the vertical resolution of the image field -->

            <add sourceID="{9E1BF6CC-6DEF-49E9-BEF8-DC6E6CA4E10D}" targetID="{337274F2-2E48-41B1-B0B8-56C7D5F7C813}"/>

            <!-- Horizontal resolution field is mapped to the horizontal resolution of the image field -->

            <add sourceID="{8B081FF0-35CA-4DA5-AC58-9A40ACAFFC17}" targetID="{48A65837-49E3-42EE-91ED-75056DAE12D5}"/>

            <!-- BitDepth field is mapped to the BitDepth of the image field -->

            <add sourceID="{C1D814F1-6663-423A-95DF-BF524613C78D}" targetID="{A20F4915-90D5-4070-A051-5F7AAB4DDB24}"/>

            <!-- Width field -->

            <add sourceID="{68CB12D0-5C46-41A0-B04D-4B57B14896E8}" targetID="{DF3D60BC-1E58-41A2-A224-269C60A5B6BB}"/>

            <!-- Height field -->

            <add sourceID="{9D8A8798-B67A-456F-A06E-7D48E6027A13}" targetID="{68217488-CE8E-4998-8780-29816CCCD15B}"/> 

         </mapping>

         <invalidItemNameHandlers>

            <add type="Sitecore.Modules.Migrate.Utils.ItemNameHandlers.InvalidCharactersStripper, sitecore.migrationwizard" mode="on"/>

            <add type="Sitecore.Modules.Migrate.Utils.ItemNameHandlers.AtReplacer, sitecore.migrationwizard" mode="on"/>

            <add type="Sitecore.Modules.Migrate.Utils.ItemNameHandlers.DashReplacer, sitecore.migrationwizard" mode="on"/>

            <add type="Sitecore.Modules.Migrate.Utils.ItemNameHandlers.ItemNameCutter, sitecore.migrationwizard" mode="on"/>

           <add type="Sitecore.Modules.Migrate.Utils.ItemNameHandlers.DefaultInvalidItemNameHandler, sitecore.migrationwizard" mode="on"/>

         </invalidItemNameHandlers>

         <preprocessing>

         <!-- Processor which changes the template type of your media item to one of the templates defined in the Web.config.

         Change the mode attribute to 'on' if you want to use this handler -->

            <add type="Sitecore.Modules.Migrate.Utils.PreProcessors.KnownMediaTypeProcessor, Sitecore.MigrationWizard" mode="off"/>

         </preprocessing>

         <fieldHandlers>

            <add type="Sitecore.Modules.Migrate.Utils.FieldHandlers.FileFieldHandler, Sitecore.MigrationWizard" mode="on"/>

         </fieldHandlers>

         <versionHandlers>

         </versionHandlers>

         <itemHandlers>

         </itemHandlers>

      </migration>

3. Add the new data view to Sitecore data views. Add the following line to the <dataviews> section of the web.config file:

   <dataview name="DataTransfer" assembly="Sitecore.MigrationControls" type="Sitecore.Modules.Migrate.UI.Controls.ServiceDataView" Parameters=""/>

4. Register new XML controls in the configuration file. Add the following line to the <controlSources> section:

   <source mode="on" namespace="Sitecore.Modules.Migrate.Generated" folder="/sitecore modules/Migrate/ui" deep="true"/>
   

5. Configure the SoapExtension for archiving transferred data.
   Note: due to SoapExtension architecture, it is not possible to migrate data from one database to another within one Sitecore installation.
   Add the following lines to the <system.web> section:

   <webServices>
        <soapExtensionTypes>
         <add type="TransferProtocol.SoapExtensions.SoapArchiveExtension,TransferProtocol"
              priority="1"
              group="0" />
        </soapExtensionTypes>
   </webServices>

6. Add new application setting to the <appsettings> section (Sitecore 5.2.X and earlier):

• Sitecore 5.2.
  Version 5.2.0.3:

  <add key="MigrationWizardLogAssembly" value="log4net" />

  Version 5.2.0.6 and later:

  <add key="MigrationWizardLogAssembly" value="Sitecore.Logging" /> 

• Sitecore 5.1.
  Versions 5.1.1.7, 5.1.1.8 and 5.1.1.9

  <add key="MigrationWizardLogAssembly" value="log4net" />

  Version 5.1.1.11 and later

  <add key="MigrationWizardLogAssembly" value="Sitecore.log4net" />

1.1.  log4net Configuration (Sitecore 5.1)

Add the following lines to the <log4net> section to configure the logs for Migration Wizard if you use Sitecore 5.1 as target installation:

<appender name="migration" type="log4net.Appender.SitecoreLogFileAppender">
      <file value="/data/logs/migration" />
      
      <appendToFile value="true" />
      <layout type="log4net.Layout.PatternLayout">
        <conversionPattern value="%d{ABSOLUTE} %-5p [%C{2}.%M] %m%n" />
      </layout>
    </appender>

    <appender name="migration.changed" type="log4net.Appender.SitecoreLogFileAppender">
      <file value="/data/logs/migration.changed" />
      
      <appendToFile value="true" />
      <filter type="log4net.Filter.LevelRangeFilter">
     <levelMin value="INFO" />
    <levelMax value="WARN" />
      </filter>
      <layout type="log4net.Layout.PatternLayout">
        <conversionPattern value="%d{ABSOLUTE} %-5p %m%n" />
      </layout>
    </appender>
    
    <appender name="migration.failed" type="log4net.Appender.SitecoreLogFileAppender">
      <file value="/data/logs/migration.failed" />
      
      <appendToFile value="true" />
      <layout type="log4net.Layout.PatternLayout">
        <conversionPattern value="%d{ABSOLUTE} %-5p %m%n" />
      </layout>
    </appender>

    <logger name="Sitecore.Modules.Migrate" additivity="false">
      <level value="ALL"/>
      <appender-ref ref="migration" />
    </logger>
    
    <logger name="Sitecore.Modules.Migrate.ChangedItems" additivity="true">
      <level value="ALL"/>
      <appender-ref ref="migration.changed" />
    </logger>
    
    <logger name="Sitecore.Modules.Migrate.ChangedItems.FailedItems" additivity="true">
      <level value="ALL"/>
      <appender-ref ref="migration.failed" />
    </logger>

1.2.  log4net Configuration (Sitecore 5.2)

Add the following lines to the <log4net> section to configure the logs for Migration Wizard if you use Sitecore 5.2 as target installation:

<appender name="migration" type="log4net.Appender.SitecoreLogFileAppender">
      <file value="/data/logs/migration.{date}.txt" />
      
      <appendToFile value="true" />
      <layout type="log4net.Layout.PatternLayout">
        <conversionPattern value="%d{ABSOLUTE} %-5p [%C{2}.%M] %m%n" />
      </layout>
    </appender>

    <appender name="migration.changed" type="log4net.Appender.SitecoreLogFileAppender">
      <file value="/data/logs/migration.changed.{date}.txt" />
      
      <appendToFile value="true" />
      <filter type="log4net.Filter.LevelRangeFilter">
   <levelMin value="INFO" />
   <levelMax value="WARN" />
      </filter>
      <layout type="log4net.Layout.PatternLayout">
        <conversionPattern value="%d{ABSOLUTE} %-5p %m%n" />
      </layout>
    </appender>
    
    <appender name="migration.failed" type="log4net.Appender.SitecoreLogFileAppender">
      <file value="/data/logs/migration.failed.{date}.txt" />
      
      <appendToFile value="true" />
      <layout type="log4net.Layout.PatternLayout">
        <conversionPattern value="%d{ABSOLUTE} %-5p %m%n" />
      </layout>
    </appender>

    <logger name="Sitecore.Modules.Migrate" additivity="false">
      <priority value="INFO" />
      <level value="ALL"/>
      <appender-ref ref="migration" />
    </logger>
    
    <logger name="Sitecore.Modules.Migrate.ChangedItems" additivity="true">
      <priority value="INFO" />
      <level value="ALL"/>
      <appender-ref ref="migration.changed" />
    </logger>
    
    <logger name="Sitecore.Modules.Migrate.ChangedItems.FailedItems" additivity="true">
      <priority value="INFO" />
      <level value="ALL"/>
         <appender-ref ref="migration.failed" />
    </logger>

1.3.  log4net Configuration (Sitecore 5.3)

Add the following lines to the <log4net> section to configure the logs for Migration Wizard if you use Sitecore 5.3 as target installation:

<appender name="migration" type="log4net.Appender.SitecoreLogFileAppender">
  <file value="$(dataFolder)/logs/migration.{date}.txt" />

  <appendToFile value="true" />
  <layout type="log4net.Layout.PatternLayout">
    <conversionPattern value="%d{ABSOLUTE} %-5p [%C{2}.%M] %m%n" />
  </layout>
</appender>

<appender name="migration.changed" type="log4net.Appender.SitecoreLogFileAppender">
  <file value="$(dataFolder)/logs/migration.changed.{date}.txt" />

  <appendToFile value="true" />
  <filter type="log4net.Filter.LevelRangeFilter">
    <levelMin value="INFO" />
    <levelMax value="WARN" />
  </filter>
  <layout type="log4net.Layout.PatternLayout">
    <conversionPattern value="%d{ABSOLUTE} %-5p %m%n" />
  </layout>
</appender>

<appender name="migration.failed" type="log4net.Appender.SitecoreLogFileAppender">
  <file value="$(dataFolder)/logs/migration.failed.{date}.txt" />

  <appendToFile value="true" />
  <layout type="log4net.Layout.PatternLayout">
    <conversionPattern value="%d{ABSOLUTE} %-5p %m%n" />
  </layout>
</appender>

<logger name="Sitecore.Modules.Migrate" additivity="false">
  <level value="ALL"/>
  <appender-ref ref="migration" />
</logger>

<logger name="Sitecore.Modules.Migrate.ChangedItems" additivity="true">
  <level value="ALL"/>
  <appender-ref ref="migration.changed" />
</logger>

<logger name="Sitecore.Modules.Migrate.ChangedItems.FailedItems" additivity="true">
  <level value="ALL"/>
  <appender-ref ref="migration.failed" />
</logger>

2.  Source Service Package

You need to install a special service on the source Sitecore installation. Choose the appropriate package for your source version on the Downloads page.

By default size of the response from  service is 8 MB. If you are expecting to transfer data with large content (Media Library items with blobs) you may wish to increase this value. For this purpose all services can read this value from AppSettings section in the Web.Config file. You just need to add the key and value (in bytes) to this section as shown below:

<add key="MigrationSize" value="16777216" />.

This means that maximum response size from the service is 16MB.

3.  Supported Sitecore Versions

The table below shows between which versions of Sitecore the data may be transferred (the data is transferred from the source to the target installation).

Source	Target
4.3.2.13, 5.0.x, 5.1.1.x	5.1.x
4.3.2.13, 5.0.x, 5.1.1.x	5.2.0.3 - 5.2.0.12
5.2.0.3	5.1.x
4.3.2.13, 5.0.x, 5.1.x, 5.2.x, 5.3.0	5.3.0, 5.3.1

4.  Module Architecture

The module works in the following way:

Data is transferred from the source Sitecore installation to the target installation via a web service. The web service is supplied with a special service package which is installed on the source installation. This service provides a kind of portal for data transfer.

A Migration Wizard is installed on the target Sitecore installation. This Wizard guides you through the data transfer process.

Both installations should work simultaneously as two separate IIS sites – the Wizard on the target installation for process control and the Service on the source installation for data exporting.

Such architecture makes the module compliant with a wide range of previous Sitecore releases and independent of the database types used.

5.  Upgrade Instructions

Upgrading Data Migration Wizard from v1.5.0 to v1.5.1

to upgrade the Data Migration Wizard from version 1.5.0 to version 1.5.1 install the package and choose the following options when prompted.

• Overwrite all the assemblies from the bin folder and all xml files from the Sitecore Modules folder.

 

• No to all any other files.
• It is NOT recommended that users overwrite the migration config file as many users have their own specific settings in this file. Therefore users should merge the migration module configuration file by adding the entires from the <mapping> section and other settings manually.
• Merge\Append for the template items.

 

• Skip for all content items.

Upgrading Data Migration Service from v1.0.2 to v1.0.4

To Upgrade Data Migration Service from v1.0.2 to v1.0.3, install the package and choose 'Overwrite All' when prompted.

Upgrading from v1.1.1 to v1.1.2

To upgrade from Data Migration module v1.1.1 to v1.1.2, install the new package and choose 'Overwrite All' when prompted.

Upgrading from v1.0.1 to v1.0.2

To upgrade from Data Migration module v1.0.1 to Data Migration module v1.0.2, install the new package and choose 'Overwrite All' when prompted.  

Upgrading from v1.3.0 to v1.3.3

To upgrade from Data Migration module v1.3.0 and later to Data Migration module v1.3.3, install the new package and choose ‘Overwrite All’ when prompted.