Migration XML Files

You can modify the behavior of a basic USMT migration by using XML files; these files provide instructions on where and how the USMT tools should gather and apply files and settings. User State Migration Toolkit (USMT) 4.0 includes three XML files that you can use to customize a basic migration: the MigDocs.xml and MigUser.xml files, which modify how files are discovered on the source computer, and the MigApps.xml file, which is required in order to migrate supported application settings. You can also create and edit custom XML files and a Config.xml file to further customize your migration.

This document provides an overview of the default and custom migration XML files and includes guidelines for creating and editing a customized version of the MigDocs.xml file. The MigDocs.xml file uses the new GenerateDocPatterns function available in USMT 4.0 to automatically find user documents on a source computer.

In This Document

Overview of the Config.xml file

Overview of the MigApp.xml file

Overview of the MigUser.xml file

Overview of the MigDocs.xml file

Using multiple XML files

     XML rules for migrating user files

Creating and editing a custom XML file

     The GenerateDocPatterns function

     Understanding the system and user context

     Sample migration rules for customized versions of XML files

     Exclude rules usage examples

     Include rules usage examples

Next steps

Overview of the Config.xml file

The Config.xml file is the configuration file created by the /genconfig option of the ScanState tool; it can be used to modify which operating-system components are migrated by USMT 4.0. The Config.xml file can be used in conjunction with other XML files, such as in the following example: scanstate /i:migapps.xml /i:miguser.xml /genconfig:c:\myFolder\config.xml. When used this way, the Config.xml file can be used as a simple way to tightly control aspects of the migration, including user profiles, data, and settings, without modifying or creating other XML files. For more information about the Config.xml file, see Customize USMT XML Files and Config.Xml.

Overview of the MigApp.xml file

The MigApp.xml file installed with the USMT 4.0 includes instructions to migrate the settings for the applications listed in What Does USMT Migrate?. You must include the MigApp.xml file when using the ScanState and LoadState tools, by using the /i option in order to migrate application settings. The MigDocs.xml and MigUser.xml files do not migrate application settings. You can create a custom XML file to include additional applications. For more information, see Create a Custom XML File.

Overview of the MigUser.xml file

The MigUser.xml file includes instructions for USMT 4.0 to migrate user files based on file name extensions. You can use the MigUser.xml file with the ScanState and LoadState tools to perform a more targeted migration than using USMT without XML instructions. The MigUser.xml file will gather all files from the standard user-profile folders, as well as any files on the computer with the specified file name extensions.

The default MigUser.xml file migrates the following:

• All files from the standard user-profile folders which are described as:

  • CSIDL_MYVIDEO

  • CSIDL_MYMUSIC

  • CSIDL_DESKTOP

  • CSIDL_STARTMENU

  • CSIDL_PERSONAL

  • CSIDL_MYPICTURES

  • CSIDL_FAVORITES

  • CSIDL_QUICK LAUNCH

• Files with the following extensions:

  .qdf, .qsd, .qel, .qph, .doc*, .dot*, .rtf, .mcw, .wps, .scd, .wri, .wpd, .xl*, .csv, .iqy, .dqy, .oqy, .rqy, .wk*, .wq1, .slk, .dif, .ppt*, .pps*, .pot*, .sh3, .ch3, .pre, .ppa, .txt, .pst, .one*, .vl*, .vsd, .mpp, .or6, .accdb, .mdb, .pub

The default MigUser.xml file does not migrate the following:

• Files tagged with both the hidden and system attributes.

• Files and folders on removable drives,

• Data from the %WINDIR%, %PROGRAMFILES%, %PROGRAMDATA% folders.

• ACLS for files in folders outside the user profile.

You can make a copy of the MigUser.xml file and modify it to include or exclude standard user-profile folders and file name extensions. If you know all of the extensions for the files you want to migrate from the source computer, use the MigUser.xml file to move all of your relevant data, regardless of the location of the files. However, this may result in a migration that contains more files than intended. For example, if you choose to migrate all .jpg files, you may migrate image files such as thumbnails and logos from legacy applications that are installed on the source computer.

Overview of the MigDocs.xml file

The MigDocs.xml file uses the new GenerateDocPatterns helper function to create instructions for USMT 4.0 to migrate files from the source computer, based on the location of the files. You can use the MigDocs.xml file with the ScanState and LoadState tools to perform a more targeted migration than using USMT without XML instructions.

The default MigDocs.xml file migrates the following:

• All files on the root of the drive except %WINDIR%, %PROGRAMFILES%, %PROGRAMDATA%, or %USERS%.

• All folders in the root directory of all fixed drives. For example: c:\data_mail\*[*]

• All files from the root of the Profiles folder, except for files in the system profile. For example: c:\users\name[mail.pst]

• All folders from the root of the Profiles folder, except for the system-profile folders. For example: c:\users\name\new folder\*[*]

• Standard shared folders:

  • CSIDL_COMMON_DESKTOPDIRECTORY

  • CSIDL_COMMON_FAVORITES

  • CSIDL_COMMON_DOCUMENTS

  • CSIDL_COMMON_MUSIC

  • CSIDL_COMMON_PICTURES

  • CSIDL_COMMON_VIDEO

  • FOLDERID_PublicDownloads

• Standard user-profile folders for each user:

  • CSIDL_MYDOCUMENTS

  • CSIDL_MYPICTURES

  • FOLDERID_OriginalImages

  • CSIDL_MYMUSIC

  • CSIDL_MYVIDEO

  • CSIDL_FAVORITES

  • CSIDL_DESKTOP

  • CSIDL_QUICKLAUNCH

  • FOLDERID_Contacts

  • FOLDERID_Libraries

  • FOLDERID_Downloads

  • FOLDERID_SavedGames

  • FOLDERID_RecordedTV

The default MigDocs.xml file will not migrate the following:

• Files tagged with both the hidden and system attributes.

• Files and folders on removable drives.

• Data from the %WINDIR%, %PROGRAMDATA%, and %PROGRAMFILES% folders.

• Folders that contain installed applications.

You can also use the /genmigxml option with the ScanState tool to review and modify what files will be migrated. For more information, see the Creating and editing a custom XML file section of this document.

Using multiple XML files

You can use multiple XML files with the ScanState and LoadState tools. Each of the default XML files included with or generated by USMT 4.0 is configured for a specific component of the migration. You can also use custom XML files to supplement these default files with additional migration rules.

For example, you can use all of the XML migration file types for a single migration, as in the following example:

Scanstate <store> /config:c:\myFolder\config.xml /i:migapps.xml /i:migdocs.xml /i:customrules.xml

XML rules for migrating user files

If your data set is unknown or if many files are stored outside of the standard user-profile folders, the MigDocs.xml is a better choice than the MigUser.xml file, because the MigDocs.xml file will gather a broader scope of data. The MigDocs.xml file migrates folders of data based on location. The MigUser.xml file migrates only the files with the specified file extensions.

If you want more control over the migration, you can create custom XML files. See the Creating and editing a custom XML file section of this document.

Creating and editing a custom XML file

You can utilize the /genmigxml command-line option to determine which files will be included in your migration. The /genmigxml option creates a file in a location you specify, so that you can review the XML rules and make modifications as necessary.

To generate the XML migration rules file for a source computer:

1. Click Start, click All Programs, click Accessories, right-click Command Prompt, and then click Run as.

2. Select an account with administrator privileges, supply a password, and then click OK.

3. At the command prompt, type:

   cd /d <USMTpath>
   
   scanstate.exe /genmigxml: <filepath.xml>
   

   Where <USMTpath> is the location on your source computer where you have saved the USMT 4.0 files and tools, and <filepath.xml> is the full path to a file where you can save the report. For example, type:

   cd /d c:\USMT
   
   scanstate.exe /genmigxml:"C:\Documents and Settings\USMT Tester\Desktop\genMig.xml"
   

The GenerateDocPatterns function

The MigDocs.xml file calls the GenerateDocPatterns function which takes three Boolean values. You can change the settings to modify the way the MigDocs.xml file generates the XML rules for migration.

<pattern type="File">C:\Program Files\Microsoft Office\*[*.doc]</pattern>

Usage:

MigXmlHelper.GenerateDocPatterns ("<ScanProgramFiles>", "<IncludePatterns>", "<SystemDrive>")

To create include data patterns for only the system drive:

<include filter='MigXmlHelper.IgnoreIrrelevantLinks()'>

     <objectSet>

        <script>MigXmlHelper.GenerateDocPatterns ("FALSE","TRUE","TRUE")</script>

     </objectSet>

</include>

To create an include rule to gather files for registered extensions from the %PROGRAMFILES% directory:

<include filter='MigXmlHelper.IgnoreIrrelevantLinks()'>

     <objectSet>

        <script>MigXmlHelper.GenerateDocPatterns ("TRUE","TRUE","FALSE")</script>

     </objectSet>

</include>

To create exclude data patterns:

<exclude filter='MigXmlHelper.IgnoreIrrelevantLinks()'>

     <objectSet>

        <script>MigXmlHelper.GenerateDocPatterns ("FALSE","FALSE","FALSE")</script>

     </objectSet>

</exclude>

Understanding the system and user context

The migration XML files contain two <component> elements with different context settings. The system context applies to files on the computer that are not stored in the User Profiles directory, while the user context applies to files that are particular to an individual user.

System context

The system context includes rules for data outside of the User Profiles directory. For example, when called in a system context in the MigDocs.xml file, the GenerateDocPatterns function creates patterns for all common shell folders, files in the root directory of hard drives and folders located at the root of hard drives. The following folders are included:

• CSIDL_COMMON_DESKTOPDIRECTORY

• CSIDL_COMMON_FAVORITES

• CSIDL_COMMON_DOCUMENTS

• CSIDL_COMMON_MUSIC

• CSIDL_COMMON_PICTURES

• CSIDL_COMMON_VIDEO

• FOLDERID_PublicDownloads

User context

The user context includes rules for data in the User Profiles directory. When called in a user context in the MigDocs.xml file, the GenerateDocPatterns function creates patterns for all user shell folders, files located at the root of the profile and folders located at the root of the profile. The following folders are included:

• CSIDL_MYDOCUMENTS

• CSIDL_MYPICTURES

• FOLDERID_OriginalImages

• CSIDL_MYMUSIC

• CSIDL_MYVIDEO

• CSIDL_FAVORITES

• CSIDL_DESKTOP

• CSIDL_QUICKLAUNCH

• FOLDERID_Contacts

• FOLDERID_Libraries

• FOLDERID_Downloads

• FOLDERID_SavedGames

• FOLDERID_RecordedTV

Sample migration rules for customized versions of XML files

Exclude rules usage examples

In the examples below, the source computer has a .txt file called "new text document" in a directory called "new folder". The default MigDocs.xml behavior migrates the new text document.txt file and all files contained in the "new folder" directory. The rules generated by the function are:

<pattern type="File">d:\new folder\[new text document.txt]</pattern>

<pattern type="File">d:\new folder\*[*]</pattern>

To exclude the new text document.txt file as well as any .txt files in “new folder”, you can do the following:

Example 1 : Exclude all .txt files in a folder

To exclude Rule 1, there needs to be an exact match of the file name. However, for Rule 2, you can create a pattern to exclude files by using the file extension.

<exclude>

     <objectSet>

        <pattern type="File">D:\Newfolder\[new text document.txt]</pattern>

         <pattern type="File">D:\New folder\*[*.txt]</pattern>

     </objectSet>

</exclude>

Example 2 : Use the UnconditionalExclude element to give a rule precedent over include rules

If you do not know the file name or location of the file, but you do know the file extension, you can use the GenerateDrivePatterns() function. However, the rule will be less specific than the default include rule generated by the MigDocs.xml file, so it will not have precedent. You must use the <UnconditionalExclude> element to give this rule precedent over the default include rule. For more information about the order of precedence for XML migration rules, see Conflicts and Precedence.

<unconditionalExclude>

     <objectSet>

        <script>MigXmlHelper.GenerateDrivePatterns ("*[*.txt]", "Fixed")</script>

     </objectSet>

</unconditionalExclude>

Example 3 : Use a UserandSystem context component to run rules in both contexts

If you want the <UnconditionalExclude> element to apply to both the system and user context, you can create a third component using the UserandSystem context. Rules in this component will be run in both contexts.

<component type="Documents" context="UserandSystem">

   <displayName>MigDocExcludes</displayName>

   <role role="Data">

     <rules>

       <unconditionalExclude>

         <objectSet>

                <script>MigXmlHelper.GenerateDrivePatterns ("*[*.txt]", "Fixed")</script>

         </objectSet>

       </unconditionalExclude>

     </rules>

   </role>

</component>

For more examples of exclude rules that you can use in custom migration XML files, see Exclude Files and Settings.

Include rules usage examples

The application data directory is the most common location that you would need to add an include rule for. The GenerateDocPatterns function excludes this location by default. If your company uses an application that saves important data to this location, you can create include rules to migrate the data. For example, the default location for .pst files is: %CSIDL_LOCAL_APPDATA%\Microsoft\Outlook. The Migapp.xml file contains migration rules to move only those .pst files that are linked to Microsoft Outlook. To include .pst files that are not linked, you can do the following:

Example 1 : Include a file extension in a known user folder

This rule will include.pst files that are located in the default location, but are not linked to Microsoft Outlook. Use the user context to run this rule for each user on the computer.

<include filter='MigXmlHelper.IgnoreIrrelevantLinks()'>

     <objectSet>

        <pattern type="File">%CSIDL_LOCAL_APPDATA%\Microsoft\Outlook\*[*.pst]</pattern>

     </objectSet>

</include>

Example 2 : Include a file extension in Program Files

For locations outside the user profile, such as the Program Files folder, you can add the rule to the system context component.

<include filter='MigXmlHelper.IgnoreIrrelevantLinks()'>

     <objectSet>

        <pattern type="File">%CSIDL_PROGRAM_FILES%\*[*.pst]</pattern>

     </objectSet>

</include>

For more examples of include rules that you can use in custom migration XML files, see Include Files and Settings.

Next steps

You can include additional rules for the migration in the MigDocs.xml file or other XML migration files. For example, you can use the <locationModify> element to move files from the folder where they were gathered to a different folder, when they are applied to the destination computer. For more information, see the XML reference.

You can use an XML schema (MigXML.xsd) file to validate the syntax of your customized XML files. For more information, see USMT resources.