Migration module config file

Installation package of the Migration wizard for Sitecore 5.3.1 will install the configuration file for the module (by default the file will be located here: '/app_config/migrationmodule.config'). The configuration of the transferring process is set in this file. The MigrationModule.config file consists of the following sections:

contentMapping
mapping
invalidItemNameHandlers
preprocessing
fieldHandlers
itemHandlers
versionHandlers

The same configuration sections are present for Migration module for Sitecore 5.1.X and Sitecore 5.2.X, except for the contentMapping section, but it is placed in the Web.config file directly. Migration section contains the same sections as were described earlier but the versionHandler and itemHandler sections are empty by default.

1. contentMapping Section

This section defines the rules for the transferred items. Content of the fields of items which pass the requirements specified in this section will be processed (source substrings will be replaced with target substrings)

Below we provide two examples where this functionality is extremely useful:

Some field types, for example integer or number, which were present in Sitecore CMS 4.3.2.13 don’t exist in the current version. So, during migration of the custom templates we should change these field types to the appropriate field types in the target version (e.g. text). So we should define content replacers to be used for the items which are based on the ‘Template field’ template and have an ID which is equal to the ‘FieldType’ field ID.
Due to the fact that processing of the field values is performed before the field is added to Sitecore, we can change some invalid values, for example language names. Sitecore CMS 4.3.2.13 allows to create any languages with any ISO codes even if it does not exist in the default set of the languages (e.g. ISO=English etc). There were two different ways to handle this problem before: replace such language using a script in the source solution or register invalid language in target solution, convert the solution and rename the language using Sitecore CMS functionality afterwards. Now, using the contentMapping section, you can create the replacer which corrects the language before it is added to the target Sitecore solution on the fly.

This section describes mappings for the content of fields. The following sections are described: Templates, Items, Fields and contentEntries:

Templates section defines the list of template Ids. Content of the fields of the items which are based on these templates will be processed.
Items section defines the list of the items to be processed.
Fields section defines the list of field IDs which will be processed

(all sections above can use either a correct ID or the ‘*’ char as a value. ‘*’ means all IDs)
ContentEntries section defines the list of the contentEntry items. ContentEntry item has two attributes: Source and Target node (see the sample below):

<contentEntry matchWholeText="true" caseSensitive="false">
<source>integer</source>
<target>text</target>
</contentEntry>
- matchWholeText =”true” means that if the content of the transferred field is equal to the content in the source definition then the content of the transferred field will be replaced with the text in the Target definition. If matchWholeText is false then all parts of the transferred field which are equal to the text defined in the Source definition will be replaced with the text which is defined in the target definition.
- caseSensitive option can be applied to the whole content only (matchWholeText =”true”) and if this attribute is false then the comparison operation will be case insensitive.

For example: we have a language item in Sitecore CMS 4.3.2.13 with an incorrect ISO code – ‘danish’. We are planning to migrate the solution to Sitecore CMS 5.3.X and we don’t want to make any changes to the source solution as well as register a language with ‘danish’ ISO code in the target solution. Migrating this language item will give the error:

Could not parse the language 'danish'. Note that a custom language name must be on the form: isoLanguageCode-isoRegionCode-customName. The language codes are two-letter ISO 639-1, and the regions codes are are two-letter ISO 3166. Also, customName must not exceed 8 characters in length. Valid example: en-US-East. For the full list of requirements, see: http://msdn2.microsoft.com/en-US/library/system.globalization.cultureandregioninfobuilder.cultureandregioninfobuilder.html

The mapping functionality allowa to handle this problem by adding 2 mappings: one for the ISO field for the items based on the Language template and the second one for the Language of the item.

The first mapping is simple:

        <mapping>
           <templates>
              <templateID>{F68F13A6-3395-426A-B9A1-FA2DC60D94EB}</templateID>
           </templates>
           <items>
              <itemID>*</itemID>
           </items>
           <fields>
              <fieldID>{C437E416-8948-427D-A982-8ED37AE3F553}</fieldID>
           </fields>
           <contentEntries>
              <contentEntry matchWholeText="true" caseSensitive="false">
                 <source>danish</source>
                 <target>da</target>
              </contentEntry>
          </contentEntries>
         </mapping>

Where {F68F13A6-3395-426A-B9A1-FA2DC60D94EB} is the ID of the Language template and {C437E416-8948-427D-A982-8ED37AE3F553} – the ID of the ISO field in this template

The second mapping is needed to correct the language description of the item. See the text in bold in the xml structure of the item:

To change the ‘danish’ to ‘da’ in the version description we should add the special constant ‘ItemLanguage’ which describes the language for each item version. It is possible to add additional constants for the other values such as ‘name’, ‘key’, etc.

So the mapping is:

<mapping>
           <templates>
              <templateID>*</templateID>
           </templates>
           <items>
              <itemID>*</itemID>
           </items>
           <fields>
              <fieldID>__ItemLanguage</fieldID>
           </fields>
           <contentEntries>
              <contentEntry matchWholeText="true" caseSensitive="false">
                 <source>danish</source>
                <target>da</target>
              </contentEntry>
           </contentEntries>
         </mapping>

2. Mapping Section

This section defines mapping of the item IDs during transferring. By default, this section contains mapping for correct transfer of media items from Sitecore 4.3.2.X and Sitecore 5.1.X, 5.2.X. Section can contain different mapping for different Sitecore version. See the mapping section for Sitecore 5.3:

     <!-- 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}"/>        
<!-- media templates mapping. Used for correct transferring of the media templates such as "__Image", "__JPG image" etc
        to the unversioned media templates of the Sitecore 5.3.X. Remove or comment this mapping if you going ot transfer 
        media items from the Sitecore 5.3 -->
     <!-- Image template -->
         <add sourceID="{C97BA923-8009-4858-BDD5-D8BE5FCCECF7}" targetID="{F1828A2C-7E5D-4BBD-98CA-320474871548}"/>
         <!-- Path field -->
         <add sourceID="{B48AF244-B099-44CE-B8B9-3D3C14194C06}" targetID="{47FA03A6-A52C-4BE7-A726-B3A8BB3254D6}"/>
         <!-- Alt field -->
         <add sourceID="{8CF45D0E-ADD4-4772-911A-AC6FC50F9C7D}" targetID="{65885C44-8FCD-4A7F-94F1-EE63703FE193}"/>
         <!-- Description field -->
         <add sourceID="{240432D4-3604-46B1-A0F5-78ABC6766486}" targetID="{BA8341A1-FF30-47B8-AE6A-F4947E4113F0}"/>
         <!-- Title field -->
         <add sourceID="{DC34A2CA-4E0A-4640-B375-62B79F67AFF8}" targetID="{3F4B20E9-36E6-4D45-A423-C86567373F82}"/>
     <!-- File template -->
         <add sourceID="{611933AC-CE0C-4DDC-9683-F830232DB150}" targetID="{962B53C4-F93B-4DF9-9821-415C867B8903}"/>
         <!-- Path field -->
         <add sourceID="{F8339D09-C19B-452A-A5A8-A189972DF23A}" targetID="{47FA03A6-A52C-4BE7-A726-B3A8BB3254D6}"/>
         <!-- Description field -->
         <add sourceID="{EBEB197C-376E-47C4-95D7-7FC26682D12E}" targetID="{BA8341A1-FF30-47B8-AE6A-F4947E4113F0}"/>
         <!-- Title field -->
         <add sourceID="{E625E7DA-F988-4442-A598-D21040EC9815}" targetID="{3F4B20E9-36E6-4D45-A423-C86567373F82}"/>
    <!-- GIF template to unversioned Image template -->
         <add sourceID="{27F12339-1571-482B-B39D-B03004CCF2AD}" targetID="{F1828A2C-7E5D-4BBD-98CA-320474871548}"/>
         <!-- Path field -->
         <add sourceID="{ABD37B99-FAF4-449B-854F-82C0DAF73B3D}" targetID="{47FA03A6-A52C-4BE7-A726-B3A8BB3254D6}"/>
         <!-- Alt field -->
         <add sourceID="{D7F6DFE2-151F-4023-8A4A-8D7FE202C39D}" targetID="{65885C44-8FCD-4A7F-94F1-EE63703FE193}"/>
         <!-- Description field -->
         <add sourceID="{94478368-C3C2-45CC-8D27-C877B416DF14}" targetID="{BA8341A1-FF30-47B8-AE6A-F4947E4113F0}"/>
         <!-- Title field -->
         <add sourceID="{C17E1045-188C-46F6-B3FD-3997809BEA1A}" targetID="{3F4B20E9-36E6-4D45-A423-C86567373F82}"/>
         <!-- Width field -->
         <add sourceID="{DF3D60BC-1E58-41A2-A224-269C60A5B6BB}" targetID="{22EAC599-F13B-4607-A89D-C091763A467D}"/>
         <!-- Height field -->
         <add sourceID="{68217488-CE8E-4998-8780-29816CCCD15B}" targetID="{DE2CA9E4-C117-4C8A-A139-1FF4B199D15A}"/>
         <!-- 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 JPG template -->
         <add sourceID="{2EE734A4-D085-45D1-B924-66F799CC8D2C}" targetID="{DAF085E8-602E-43A6-8299-038FF171349F}"/>
         <!-- Path field -->
         <add sourceID="{05193A2D-F4EB-463C-891A-97C2CB3D84FB}" targetID="{47FA03A6-A52C-4BE7-A726-B3A8BB3254D6}"/>
         <!-- Alt field -->
         <add sourceID="{380E074F-A4AE-451B-B1CA-A6E8B3DB479A}" targetID="{65885C44-8FCD-4A7F-94F1-EE63703FE193}"/>
         <!-- Description field -->
         <add sourceID="{2A9F5FCB-88F1-4EC8-B4E6-F8DF6D527CB5}" targetID="{BA8341A1-FF30-47B8-AE6A-F4947E4113F0}"/>
         <!-- Title field -->
         <add sourceID="{DC065C5F-53DF-4525-853C-A1D888B25431}" targetID="{3F4B20E9-36E6-4D45-A423-C86567373F82}"/>
         <!-- Width field -->
         <add sourceID="{68CB12D0-5C46-41A0-B04D-4B57B14896E8}" targetID="{22EAC599-F13B-4607-A89D-C091763A467D}"/>
         <!-- Height field -->
         <add sourceID="{9D8A8798-B67A-456F-A06E-7D48E6027A13}" targetID="{DE2CA9E4-C117-4C8A-A139-1FF4B199D15A}"/>
         <!-- 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}"/>
<!-- end media templates mapping -->

This mapping handles problems with transferring images to Sitecore 5.3. Sitecore 5.3 has two types of media templates: versioned and unversioned media templates. The Image and File template from Sitecore 4.3.2.X and Sitecore 5.1/5.2 have unversioned field ‘path’, so it will be correct if we transfer them to the Unversioned image and file template from Sitecore 5.3 which has a shared ‘path’ field. But there is a big problem, as we have different IDs for these templates in the target and source instances. Moreover, Sitecore 4.3.2.x has no template inheritance which is available in Sitecore 5.3. Thus we should not only map templates to each other, but also map their fields which are inherited from other templates. See the fist section in the mappings:

This section maps Image template ID from Sitecore 4.3.2.X to unversioned Image template ID in Sitecore 5.3:

Where {C97BA923-8009-4858-BDD5-D8BE5FCCECF7} is the ID of the Image template in Sitecore 4.3.2.X and {F1828A2C-7E5D-4BBD-98CA-320474871548} is the ID of the unversioned image in Sitecore 5.3. All other field mappings (alt, description, path, etc) are mapped in the same way.

Note (For Sitecore 5.3 only): If you are going to transfer data from Sitecore 5.3 to Sitecore 5.3, you should remove or comment all mappings to the media templates.

Note (For Sitecore 5.3 only): If you are going to transfer without inserting into blob fields and your Sitecore 4.3.2.X solution has the Media module installed, then after migration the height and width fields for media items which were based on the “__JPG Image” and “__GIF Image” templates will be filled by values from the one of the transferred language from the item. We have such behavior because these fields are shared in the unversioned Image template in Sitecore 5.3 but they are versioned in Sitecore 4.3.2.X. So if the value for these fields is filled not for all languages of this item, it is possible that after migration they will be empty (if the language with empty fields was transferred).

3. invalidItemNameHandlers Section

This section describes the classes which are used for handling invalid item names. For example, in Sitecore 4.3.x it was possible to create items the names of which contained some characters which are denied in Sitecore 5.3 (for example, ‘/’, ‘&’ etc.). When users try to migrate an item with such names, the Migration Wizard tries to change the name. For these purposes it uses the classes defined in the invalidItemNameHandlers section. By default, this section has the following handlers:

</invalidItemNameHandlers>

As the Migration Wizard converts items with incorrect names, it will use the “Sitecore.Modules.Migrate.Utils.ItemNameHandlers.InvalidCharactersStripper” class instance first. If the name is still incorrect, it will use the “Sitecore.Modules.Migrate.Utils.ItemNameHandlers.AtReplacer” class instance and so on.

You can manage the handlers which will be used during the migration process by adding, deleting handlers or changing the ‘mode’ attribute for the appropriate handler. To add your own handlers, you should add new records to this section. Your class should implement the “Sitecore.Modules.Migrate.Utils.IInvalidItemNameHandler” interface which is defined in the Sitecore.MogrationWizard asembly.

4. preprocessing Section

This section describes preprocessors which will process data before transferring. These processors can make changes in the transferred data before it will be processed by the wizard. You can implement your own pre-processor. This processor should implement the “Sitecore.Modules.Migrate.Utils.IPreProcessor” interface which has only one method – Process. This method takes the array of deserialized versions for the transferred item and transferred options.

By default, this section has two processors – KnownMediaTypeProcessor and DomainEntityProcessor.

The KnownMediaType processor is used for correcting templates for transferred media items. Sitecore 5.3 has some additional media templates such as “Flash”, “Jpeg”, “Mp3” etc. It would be nice if items which were based on the Image or File templates in the earlier versions of Sitecore but referred to the files with a known extension (see web.config's Media section for Sitecore 5.3) are based on the appropriate templates after transferring. For example, a media item based on the File template which refers to the flash file (*.swf) after transferring should have not the 'File' but 'Flash' template.

The KnownMediaType handler resolves the file extensions and changes the type of the template for media items during transferring. It is disabled by default. Change the ‘mode’ attribute value to enable handler.

Note (Sitecore 5.3.1): this preprocesor is enabled by defoult for Sitecore 5.3.1.

The same situation with Sitecore 5.1-5.2 but by default these instances of Sitecore have only 2 media templates (File and Image). But this processor may be useful for transferring media from Sitecore 4.3.2.X (some images, such as bmp are uploaded with the File template instead of Image).

The DomainEntityProcessor is used to prevent adding users or roles with the same name to the same domain.

5. fieldHandlers Section

In this section the handlers for each field to be transferred are configured. There are 3 field handlers in this section by default:

FileFieldHandler is used to correct the file field format (it has been changed since Sitecore CMS 5.3.0)
ImageFieldHandler and HTMLFieldHandler are used to correct links to the media items.

These handlers have additional parameters:

CreateMediaItems.
If the value is on, then the new media items will be created in the “Migration folder” of the Media Library using the links to the physical files which still don’t exist in the Media Library.
ProcessMediaForFolders.
Media items will be created only if their paths start with this value.

HTMLFieldHandler allows you to process values which are stored in the ‘html’ and ‘rich text’ field types. It scans the values and changes the references to physical files to the correct references to media items. This handler has additional parameters: ProcessLinks=on,processImages=on,processFlash=on,createMediaItems=off,processMediaForFolders=|/upload/|. Each parameter is described below:

ProcessLinks – parameter which allows/denies changing links to the media items in Html fields.
ProcessImages– parameter which allows/denies changing links to the media images in Html fields.
ProcessFlash - parameter which allows/denies changing links to the flashes in Html fields.
processMediaForFolders and createMediaItems are working in the same way as FileField and ImageField handlers.

Note: each field handler should be as simple as possible because each field handling is time consuming.

Delete this handler if you don’t need to change the references in your image fields.

You can add your own handler by implementing a new class which implements the “Sitecore.Modules.Migrate.Utils.IFieldHandler” interface which is defined in the Sitecore.MogrationWizard assembly and registering your type in the fieldHandlers section. If you want to use parameters in you handler, you can inherit your handler from the “Sitecore.Modules.Migrate.Utils.BaseHandler” abstract class which implements the functionality of the initialization parameters.

6. itemHandlers Section

This section defines the handlers for items to be transferred. When an item is transferred, the handlers defined in the itemHandlers section are called. These handlers perform the postprocessing of the transferred items.

By default this section consists of the following handlers: proxy, rich text and SitecoreUser which are enabled by default.

ProxyItemHandler
Use to handle proxy items (go to the /sitecore/system.proxies item and fill the appropriate fields of the proxy item)
RichTextReplacer
Use to change the html field type to the rich text type. Now you can use the contentMapping instead of this handler.
SitecoreUser
Use to assign the ‘Sitecore Client Authoring’ role to the transferred Sitecore client users. This functionality is needed because in the current Sitecore CMS 5.3.1 version a user should have ‘Write’ right to the language item to be an Editor. Previous Sitecore versions didn’t check this. So all transferred users should have this right by default. More about Sitecore client roles you can find here:
http://sdn.sitecore.net/Articles/Security/Sitecore%20Client%20Roles.html

Note: in the earlier versions of Sitecore CMS this section contained only 2 handlers. The SitecoreUser handler was added in the version of the module for Sitecore CMS 5.3.

Take a look at the proxy item. In the earlier versions of Sitecore (5.2 or 5.1) proxy items had 3 fields and could be created in any place in the content tree. In Sitecore 5.3 we have a special place for proxy items (/sitecore/system/proxies) and proxy items have an additional field (“source”). Thus, to correctly transfer proxy items from earlier versions of Sitecore, the proxy handler is implemented. It examines the template of the transferred item and processes it according to certain rules.

Users can include their own item handlers by implementing classes which implement the “Sitecore.Modules.Migrate.Utils.IItemHandler” which is defined in the Sitecore.MogrationWizard assembly and registering their types in the itemHandlers section.

For example, consider the functionality which replaces the “html” field type by the “rich text” type during transferring (the RichTextReplacer is included into configuration file by default). Sitecore 5.3 has the new “rich text” field type which is the preferred way to store formatted text. The code of the html field handler is shown below:

namespace HtmlToRichTextReplacer
{
   public class RichTextReplacer : IItemHandler
   {
      #region IItemHandler Members

      public void HandleItem(Sitecore.Data.Items.Item item, TransferredItem[] sourceVersions, TransferOptions options)
      {
         if ((item != null) && (item.TemplateID == TemplateIDs.TemplateField))
         {
            if (string.Compare(item["Type"], "html", true) == 0)
            {
               item["Type"] = "rich text";
            }
         }
      }

      #endregion
   }
}

The main idea of this handler is checking the transferred item. If an item has template field and its type is html, than change it to the “rich test”. To convert item fields to “rich text”, you should simply convert its template.

If you include this handler in the itemHanlers section of the MigrationModule.config file, all “html” fields of the source templates will be exchanged to “rich text”.

7. versionHandlers

This section defines handlers for each item version to be transferred. When an item version is transferred, the handlers defined in the versionHandlers section are called. These handlers perform the postprocessing of the transferred item versions.

By default, there is only one handler version in the configuration file – the language handler - which is used for correcting the name of the language item. But if you want to transfer media files to Sitecore database, you should change the value of the ‘mode’ attribute to ‘on’ for the items defined below:

The MediaPath handler collects information about transferred media items. This information is used during content items transferring.

The Media handler fills the blob fields for media items with media streams.

Note: Sitecore 5.3.1

By default, there are two enabled handlers in the configuration file – the language handler - which is used for correcting the name of the language item and MediaHandler – which is used for correct handling MediaItems (see detailed description below). But if you want to use HtmlFieldHandler, you should change the value of the ‘mode’ attribute to ‘on’ for the items defined below:

MediaHandler enabled by default and used for copying media stream to blob or to the Media.BaseFolder (it depends from the parameters for this handler).

Parameters:

UploadAsBlob=on - means that file will be loaded to the database during migration

UploadAsBlob=off - means that file will be downloaded to the special folder which is defined in the web.config file (Media.BaseFolder setting)

OverwriteFiles=on - useful only for UploadAsBlob=off mode and means that media file with the same path will be overridden during migration