Tips for Integrating USMT 3.0 into BDD 2007

First, some background information.

We use the User State Migration Tool 3.0 as part of the user state migration process in BDD 2007 (both Lite Touch and Zero Touch deployments). Unlike previous versions of BDD, we don't run USMT from the network. Instead, we install USMT 3.0 locally on the computer, first in the old operating system for capturing user state, and later in the new operating system for restoring it. Why install it locally? Well, there are four main reasons:

The USMT 3.0 installation contains subfolders with "migration plug-in DLLs" and manifest files used for the XP/2K-to-Vista migration process. Because of limitations in the SMS 2003 OS Deployment Feature Pack (OSD), there is no way to retain this folder structure in an OSD package. So it's easiest to just include the single-file installers in the OSD package.
Some customers experienced issues where network glitches during migrations caused USMT failures, even when USMT itself contained retry logic when writing user state to the network. This happened because the USMT executables and DLLs were no longer available because of the network glitch, causing USMT to crash before it could retry. (Yes, I would be very afraid to be having to deploy a new OS on such a network, but sometimes you have no choice...) With the USMT files installed locally, they will always be available.
You may need to support a migration from x86 to x64. Since the file names for the two different platform versions of USMT are the same, there is no way to have both sets of files in a single OSD package.
It's possible that a patch could be provided for USMT 3.0 at some point. This patch could be installed dynamically on top of the installed version of USMT.

But there was one complication and one glitch in the process. First, the complication: There are four different installers:

InstallUSMT30_x86_2000andXP.exe, for Windows 2000 and Windows XP (x86 verion).
InstallUSMT30_x64_XP.exe, for Windows XP x64 only.
InstallUSMT30_x86_vista.msu, for Windows Vista x86. (MSU files are the subject for another posting.)
InstallUSMT30_x64_vista.msu, for Windows Vista x64.

So in most cases, you'll need at least two of these for any migration. That's simple enough, since the ZTIUserState.wsf script figures out which one is needed and knows how to install each one. Then there's the glitch: Due to a bug in the Vista installation program, WUSA.EXE (used to install MSU files), USMT 3.0 would not install quietly using the standard "/quiet" switch. This resulted in a workaround implemented in the ZTIUserState.wsf script and described in the BDD 2007 release notes (which hopefully you've read):

An issue exists in which BDD 2007 is unable to install USMT 3.0 on computers silently during deployment. Until this issue is resolved in USMT 3.0, repeat the following steps for the x86 and x64 versions of USMT 3.0 to repackage their files in to cabinet files from which BDD 2007 can extract USMT 3.0:

1. Manually install the x86 or x64 version USMT 3.0 on a computer running Windows XP or Windows Vista.
2. Copy C:\Program Files\BDD 2007\Samples\USMT30_platform.ddf, where platform is either x86 or x64, from a computer on which BDD 2007 is installed. If USMT 3.0 is installed in a location other than the default (C:\Program Files\USMT30), edit USMT30_platform.ddf to indicate its path.
3. Run the command makecab /F USMT30_platform.ddf; then, copy the .cab file it creates (USMT30_platform.cab) to \Tools\platform folder in the BDD 2007 distribution share.

Fortunately, since the release of USMT 3.0 there has been a hotfix made available for Windows Vista to fix this "/quiet" installation problem, so if you include this fix in your Windows Vista image you won't need to worry about the workaround above. See http://support.microsoft.com/kb/929761/en-us for more information on that.

Now, let's talk some about customization.

You might not want to use the default USMT 3.0 settings for your deployment. You may choose to create your own XML files, or to customize the provided XML files. Some examples of the types of changes you might want to make:

Capturing an additional document type by specifying the file extension to look for.
Adding an additional set of application settings (via registry keys) to capture.
Specifying a directory for USMT to grab.

One customization you probably don't want to make: removing stuff from the default XML files. It's better to use a CONFIG.XML file to do that instead, but more on that later. Going into the specifics of how to make the XML customizations like those I've listed above could be the subject of a book in itself (any takers?), so let's focus instead on the process of making use of the files that you've created or customized. First, test your changes before trying to add them into a real deployment. You can run "scanstate.exe" manually to figure out if your customizations actually work - that's a lot easier than going through an hour-long process just to figure out that you missed something.

Once you've verified that your customizations work as expected, now you need to be able to tell BDD and USMT to use those new XML files. So how do you do that? Well, you need to specify the list of files on the command line that executes "scanstate.exe". But the BDD ZTIUserState.wsf script builds that command line on the fly. It uses a list property to figure out what XML files should be specified through "/i" parameters to "scanstate.exe". But if you don't specify any values for that list property, it assumes that it should use the three default files:

miguser.xml
migapp.xml
migsys.xml

Remember the discussion above about USMT 3.0 being installed locally? Well, by default the original copies of these three files are installed with it. So, if you have customized these files you need to place the updated versions somewhere that the ZTIUserState.wsf script can find them. For Lite Touch, it checks a variety of locations on the deployment point:

In the "USMT" directory (e.g. \distribution\usmt)
In the "Tools" directory or a platform specific directory under it (e.g. \distribution\tools, \distribution\tools\x86)
In the "Templates" directory (e.g. \distribution\templates)
In the "Scripts" directory (e.g. \distribution\scripts)

Take your pick. The same applies for new files: just copy them into one of these folders. But for Zero Touch, it's a little more complicated, as the files need to be part of the OSD package. I would suggest the following steps:

Copy the new or updated files into \distribution\tools\x86.
Update the OSD deployment point, which causes the files to be replicated to each of the ZTI build directories, e.g. \zti\mybuild.
From the SMS 2003 MMC, edit the OSD program properties. On the existing ZTI custom action, add the new or updated files to the list of files required for the custom action.
Refresh the SMS distribution points for this package.

After doing this, the updated XML files should be in the package directory on all of the SMS distribution points, and the ZTIUserState.wsf script knows to look for them there.

But how do you let the ZTIUserState know that you have new XML files that need to be added to the "scanstate" command line? Well, that goes back to the "list property" that I described above. The name of this parameter is "USMTMigFiles" and it is described in the "Configuration Reference" document like so:

List of files in XML format that are used by USMT (ScanState.exe) to identify user state migration information to be saved. When this property is not specified, the ZTIUserState.wsf script uses MigApp.xml, MigUser.xml, and MigSys.xml. Otherwise, ZTIUserState.wsf uses the files explicitly referenced in this property. The USMTMigFiles property has a numeric suffix (for example, USMTMigFiles1 or USMTMigFiles2).
Note: Use this property to specify the .xml files to be used by ScanState.exe instead of using the /I parameter in the ScanStateArgs property. This prevents the ZTIUserState script from potentially duplicating the same list of .xml files.

So, that means you need to configure the CustomSettings.ini rules to specify what files you want the ZTIUserState.wsf script to use. And if you specify one file, it overrides the default list of three. So let's assume that you want to use four files, the original three plus one new custom one that you've created. In this case, you'd need entries in CustomSettings.ini like so:

[Default]
USMTMigFiles1=migapp.xml
USMTMigFiles2=migsys.xml
USMTMigFiles3=miguser.xml
USMTMigFiles4=MyCustomFile.xml

The ZTIUserState.wsf script would look for each of these files (in the directories specified above). If found, it will copy them as long as the file doesn't already exist in the USMT installation directory on the local computer, by default C:\Program Files\USMT30. If the files do exist, but the file in the installation directory is older than the one that the ZTIUserState found on the network, the script will overlay the older file.

Now, back to the comment about config.xml above. USMT 3.0 has the ability to generate and use a configuration file which says what components from the XML file should actually be processed. By default, they all are. But if you wanted to limit that, e.g. don't migrate a particular application's settings or files, you could do that by turning off that component. The best way to go about this is to run "scanstate.exe" manually with /i parameters for each of the XML files you want to use, then specify the /genconfig parameter. This will generate an XML file with all the components that would be migrated on the current computer, but not a complete list of the available entries. Here's an example command:

scanstate.exe /i:migsys.xml /i:miguser.xml /i:migapp.xml /genconfig:config.xml

You would want to run this on a machine with most of the components present so that the config.xml has the largest number of entries, but it doesn't have to have all of them. What you will want to do then is remove the components that you want to capture, then change only the remaining entries to say that you don't want to capture them (migrate="no"). For example, if I did not want to capture Windows Media Player settings, I would end up with a config.xml file that looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<Configuration>
<Applications>
<component displayname="Windows Media Player" migrate="no" ID="Settings|http://www.microsoft.com/migration/1.0/migxmlext/migapp/Windows Media Player/settings||||"/>
</Applications>
</Configuration>

That brings us to the next challenge: making use of this customized config.xml file. Unfortunately, the BDD 2007 ZTIUserState.wsf script does not provide a simple way of specifying that a config.xml file should be specified on the dynamically-generated "scanstate.exe" command line. So, to use this config.xml file you will need to modify the ZTIUserState.wsf script. Fortunately, someone has already done that, so you can check out Jason Scheffelmaer's blog entry at http://www.deployvista.com/Blog/tabid/70/EntryID/22/Default.aspx for more details. Rest assured, we'll have this built into the next version of BDD. (At the time we released, we didn't know you could build a "subset" config.xml file, so we thought the file was machine-specific. Later we found out that wasn't true.)

See, it's all really simple :-)