In-Depth

Make Friends with the USMT

The User State Migration Tool may have its detractors, but it's pretty handy when it comes to migrating user settings

• By Greg Shields
• 04/22/2013

User migrations used to be cumbersome and manual, but they were seamless, right? Actually, those migrations were often a hodgepodge of misplaced data and irritated users. Back then our "user data migration" was really just a checklist of "things to remember." That list included the My Documents folder, desktop background, Internet Explorer bookmarks, any number of items that were meaningless to IT, but of profound importance to the user.

The Microsoft User State Migration Tool (USMT) is a free solution that can truly automate that manual migration checklist. It's built directly into the Microsoft Deployment Toolkit (MDT), which you can download from the Microsoft Web site. The USMT automatically gathers your users' data with the goal of inserting it back into their shiny new OSes.

Using the USMT involves building and populating a deployment share within the MDT. Once your OS images are ready, applications packaged and Task Sequences ready for deployment, you're ready to kick off a USMT-enabled migration or refresh. Log on to the user's computer, then run LiteTouch.vbs from within your deployment share's \Scripts folder.

Running the USMT might be trivially easy, but customizing it to gather data that's not part of its defaults is not. Doing so requires interacting with XML files, and no small amount of guess-and-check to determine the data you need to capture.

Fighting with Migs
Automating OS deployment with the MDT is a massive topic. In the interest of brevity, I'll assume you've already downloaded the MDT and created a ready-to-go deployment share. I'll also assume you have your OS images and other customizations ready. All that remains are a few customizations to the user state data you want to capture.

The USMT is configured to gather common user settings. These include the same kinds of bookmarks, images and documents like those discussed earlier. There are three XML files that define which user data is collected:

• MigApp.XML contains information about application settings
• MigUser.XML provides coarse control over user profile data
• MigDocs.XML can replace MigUser.XML for tighter control over document migration. Do not use MigUser.XML and MigDocs.XML at the same time.

You'll find these three XML documents in your MDT deployment share (see Figure 1). If you've looked through them, then you might have found that making sense of their content is quite difficult. Don't worry—these documents aren't intended to be edited. Working with them requires first creating another, separate XML file called Config.XML, for example.

Figure 1. MigApp.XML will let you know about a user's application settings. (Click image to view larger version.)

Before exploring the details of this Config.XML file, you need to recognize that customizing the data USMT will gather is a two-part process. First, identify the data you want to remove from the USMT defaults. Second, specify the data you wish to add.

Removing Data from a Migration
Removing data from a USMT migration is the easy part. Assuming you'll use MigApp.XML and MigUser.XML as your defaults, run the following command to create a new Config.XML file with the help of the USMT ScanState function:

Scanstate.exe /genconfig:Config.XML /i:MigApp.xml /i:MigUser.xml

Notice how this configuration file is much easier to read (see Figure 2). Each component includes the text migrate=yes. For each of these elements, you can remove an item from the list of things USMT will collect from user machines by replacing migrate=yes with migrate=no.

Figure 2. This is the type of Config.XML you'll generate to determine a migration list.(Click image to view larger version.)

You can consider the Config.XML file you've just created as a long list of all the items that USMT could migrate. Its contents are based on the instructions defined in MigApp.XML and MigUser.XML. At this point, the Config.XML file only identifies those things you don't want USMT to do.

Adding Data to a Migration
Adding items to a migration is slightly more difficult because you first need to discretely identify the data you want to add. That data can exist as system files or registry items. Your first task will be finding the data not being gathered by default and narrowing your selection to exactly what you want to collect.

Once you've identified what you want to collect, adding that information into USMT requires a bit of XML coding. This extra coding is often added into another, separate XML file -- ConfigAdd.XML, for example.

Microsoft gives you a list of some possible configurations for this XML file. In the list you'll find a series of examples that you can tune to include the specific data you need to gather. The first example is text you would use to migrate a single registry key:

<migration urlid="http://www.microsoft.com/migration/1.0/migxmlext/test">
<component type="Application" context="System">
<displayName>Component to migrate only registry value string</displayName>
<role role="Settings">
<rules>
<include>
<objectSet>
<pattern type="Registry">HKLM\Software\Microsoft\Windows\CurrentVersion\Internet Settings\Cache [Persistent]</pattern>
</objectSet>
</include>
</rules>
</role>
</component>
</migration>

Notice how much of the content is merely wrapper information for the registry path bounded by <pattern> and </pattern>. This example will migrate the registry key found at HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Internet Settings\Cache.

Migrating file and folder information requires XML content remarkably similar to what you saw in the first example. This second example migrates all files and folders from C:\EngineeringDrafts folder and subfolders to the new computer:

<migration urlid="http://www.microsoft.com/migration/1.0/migxmlext/test">
<component type="Documents" context="System">
<displayName>Component to migrate all Engineering Drafts Documents including subfolders</displayName>
<role role="Data">
<rules>
<include>
<objectSet>
<pattern type="File">C:\EngineeringDrafts\* [*]</pattern>
</objectSet>
</include>
</rules>
</role>
</component>
</migration>

Look at the differences between these two examples. You should immediately see where the important content is bounded. You should also pay attention to the asterisks, as they identify where content is migrated. Microsoft provides six more examples that show how you can discreetly include and exclude files, folders and registry items from a migration through the careful use of asterisks and other switches.

Once you've figured out the content you need to add, create your ConfigAdd.XML file from this content. Your XML file needs only a single pair of <migration> and </migration> tags. Those tags can contain one or many different components for the migration.

Validating any XML files you create can be a challenge because they must validate without errors to work within USMT. You can use the XML Notepad tool with the MigXML.XSD file on your USMT server to highlight any errors.

Integrating Migs into USMT
Your final step in this process is to integrate both the default XML files along with any custom files you've created into your MDT deployment share. Create these files under the deployment share Rules tab, which you can access in the deployment share's Properties view.

Notice the text below [Default] in Figure 3. This text points any OS deployments occurring through the deployment share to the default XML files, as well as two custom files named Presentations.XML and Config.XML.

Figure 3. The MDT deployment share Rules tab is where you want to create your default XML files. (Click image to view larger version.)

There's also a line titled ScanStateArgs. This identifies which profiles you wish to migrate. You can find the entire list of possible arguments in the TechNet Library, under "User options."

The example in Figure 3 highlights a common scenario. Using this combination of switches, USMT will only migrate domain user profiles that have logged on within the past 60 days. It will ignore local profiles. Restricting the number of profiles being migrated is useful in many situations, primarily to reduce the amount of migrated data. Reducing that data also reduces the amount of time USMT needs to complete its task.

The final item titled UserDataLocation is set to AUTO. This setting instructs USMT to use a type of migration called a hard link migration during a PC refresh. For a PC replacement, USMT will use a network share to store user information.

The following two statements are also useful. These specify the network share to be used during a PC replacement:

UDShare=\\fileServer\fileShare
UDDir=%OSDComputerName%

Giving the USMT Another Try
USMT has lived a long life. It has also earned a somewhat tarnished reputation as being difficult to use. Customizing the USMT does indeed require a bit of effort to dig through XML files and even create a few of your own. If you're willing and intrepid, the USMT provides a powerful solution for automating the otherwise paper-and-pencil checklists of migrations long past. Consider giving the USMT another try if you're tired of getting in trouble for forgetting a user's bookmarks when refreshing or migrating his computer. I know I will.