Adding custom tasks to BDD 2007 task sequences

In BDD 2007, we provide a task sequence that is preconfigured to do all of the activities needed to perform a deployment end-to-end (for Lite Touch, Zero Touch, refresh, upgrade, new computer, Windows XP, Windows Vista, etc.).  However, that doesn't mean that it does everything you need.  Depending on your particular requirements, you may need to add your own custom steps to the task sequence.  That's one of the benefits of having the task sequencer and task sequence editor available: you can make whatever adjustments you require.

Now, that doesn't mean that making those adjustments is always a simple process.  For example, let's assume you want to add batch files or simple Command Shell commands into the task sequence.  Some things to keep in mind to help assure that these run successfully:

  • Command lines that contain spaces need to be surrounded by quotes.  The parameters to those commands should not be included in the quotes (although some of them may also require quotes, depending on the command being executed).
  • Working directories should not have quotes.  The task sequencer will set the working directory via a Windows API (which doesn't need quotes) before launching the command.
  • Avoid characters that look like XML, e.g. >, <, &, as these could cause XML parsing errors.
  • Batch files can’t have UNC path working directories.  CMD.EXE does not support this, so if you specify a working directory that is a UNC path, then execute CMD.EXE or a batch file that implicitly invokes CMD.EXE, the working directory will likely end up being set to C:\WINDOWS\SYSTEM32 - possibly harmless, depending on what your batch file does, but if the working directory is necessary to find the batch file, then there is a problem.
  • Know the difference between a command processed by CMD.EXE and an executable in its own right. Don’t specify CMD.EXE commands directly without using a batch file or a “CMD.EXE /C” prefix. A few examples:
    • NET.EXE can be used directly (with or without the .exe)
    • XCOPY.EXE can be used directly (with or without the .exe)
    • COPY must be used with “CMD.EXE /C”, e.g. “CMD.EXE /C COPY C:\BLAH C:\BLAH2”, or used in a batch file.
    • MD or MKDIR must be used with “CMD.EXE /C”, or used in a batch file.
    • Other examples of commands built into CMD.EXE:  CLS, DIR, COLOR, DATE, ECHO, ERASE, EXIT, FIND, LABEL, MOVE, PATH, RD, RMDIR, START, TYPE
    • Other examples of commands that are stand-alone executables: ROBOCOPY, XCACLS, FORMAT, DISKPART, TASKKILL, SC, GPUPDATE
  • Don’t specify a working directory of “.\anything” (e.g. “.\Applications”) in the task sequence because the current working directory is not guaranteed. (Notice that when you add an application from Workbench, which does use this “.\” notation, it translates “.\” into “%DEPLOYROOT%\”. This is done at deploy time by the ZTIApplications.wsf script.)
  • The task sequencer expects all actions to indicate whether they were successful via the exit code (return code).  By default, exit code 0 and 3010 (reboot required) are considered to be successful, and all other values are considered failures.  If you task returns something other than 0 or 3010, be sure to add those valid values to the list of successful return codes on the "Options" pane.  (You can also modify your batch file to include an "exit 0" statement to force a success return code, when appropriate.)

What if you want to test out a new task sequence action without running an entire deployment to do it?  Well, you can create your own stand-alone task sequencer XML file, then tell it to run that.  (Note that the typical environment variables, e.g. DEPLOYROOT or SCRIPTROOT, won't be defined in this case.)  Here's the process that you need for that:

  1. Create a TS.XML file that looks like the following, substituting your working directory value for the “startIn” value (e.g. “C:\BLAH”) and the command between the action tags (e.g. “TEST.CMD”).

    <?xml version="1.0" encoding="utf-8"?>
    <sequence version="2.00" name="SA Task Sequence" description="SA Task Sequence">
    <step name="X" disable="false" continueOnError="false" description="" startIn="C:\BLAH" successCodeList="0 3010">
    <action>TEST.CMD</action>
    </step>
    </sequence>

  2. Save this file into “\Distribution\Tools\x86” (or x64, if you are running on an x64 OS).

  3. From command prompt (elevated, if you are running on Windows Vista or Windows Server “Longhorn”), execute this command with the working directory set to “C:\Distribution\Tools\x86”:

    start /wait tsmbootstrap.exe /env:SAStart

  4. Look at the return code before executing any more commands:

    echo %errorlevel%

    If the return code is 0, the task completed successfully. If the return code is non-zero but you didn’t see any error dialog, the TS.XML file is probably invalid. Otherwise, for all other errors the task sequencer should display an error dialog.

  5. Check the SMSTS.LOG file for additional information about the execution of the task. This will be located in %WINDIR%\SYSTEM32\CCM\LOGS\SMSTSLog if there is an SMS client installed on the machine. Otherwise, check the %TEMP% directory, or worst case, the C:\SMSTSLog directory if %TEMP% is not valid. This is a cumulative file, so start at the bottom and work your way up. (The TRACE32.EXE utility from the SMS 2003 Toolkit 2 download is useful for viewing this file.)

  6. Remove the TS.XML file from the \Distribution\Tools\x86 directory so it doesn't get in the way of future deployments.

Any other suggestions?  If so, please submit comments below and I'll continue to integrate them into this posting.