Actions

In the following I will give you a run-down of all the actions currently supported by the logon script, and how they handle different situations that might occur during execution.

Here is an overview of available actions (action names are shown in parentheses after the description):

  • Install a network printer on the computer the user is logging on to (addPrinter)
  • Copy a file (copyFile)
  • Execute a program in the background (executeInBackground)
  • Execute a program and wait for it to finish (executeAndWait)
  • Map a UNC path to a drive letter, it is possible to try a list a drive letters and use the first free (mapDrive)
  • Set the users default printer (setDefaultPrinter)

Common attributes of all actions

When defining actions, it is possible to use a number of build in dynamic wildcards, that will be translates when the logon script is running. These wildcards represent OS environment variables. Examples of wildcards include %ComputerName%, %Username%, %Desktop%, %SystemDrive% etc., look in the Wildcards section below for a complete list of available wildcards.

Since the rules are defined in a XML file, it is also possible to create static wildcards. A static wildcard is created with the ENTITY XML type, in the DOCTYPE section.

If you add <!ENTITY fs1 "fileserver1"> to the DOCTYPE declaration at the top of the XML file, you will be able to type &fs1; another place in the XML file, and have it replaced by "fileserver1" automatically. If this is completely nonsense to you, don’t worry, just have a look at the sample logonrules.xml file, and you should be able to figure it out. Otherwise, you can read more about ENTITY declaration over at xmlwriter.net.

You can define as many actions per action set as you like, just like with filters. The following example is completely valid:

<actionSet>
    <filterSet>
        <!-- filters go here -->
    </filterSet>
    <actions>
        <mapDrive drive="x" unc="\\FileServer\files" />
        <mapDrive drive="y" unc="\\FileServer\share" />
    </actions>
</actionSet>

Don’t worry if the above example is gibberish, the following sections will guide you through defining actions.

Actions will print a friendly message to the user about their doings and they will also give a descriptive error message if they fail for some reason.

Install a network printer

With the addPrinter action you can install a network printer on the computer the user is logging on to.

Attributes:

  • unc (required)

Notes / troubleshooting:

  • If you are able to install a network printer on the user’s computer by typing it's UNC path in Windows' "Run" dialog box, and hit enter, you should have no problem with this action.

Example: Install \\PrinterServer\hp on the user’s computer.

<actionSet>
    <filterSet>
        <!-- filters go here -->
    </filterSet>
    <actions>
        <addPrinter unc="\\PrinterServer\hp" />
    </actions>
</actionSet>

Copy a file

With the copyFile action you can copy a single file from a source location to destination location. There are three copy options: ifDifferent, onlyIfNotExists, alwaysCopy.

Attributes:

  • source (required)
  • destination (required)
  • option (default = ifDifferent)

Notes / troubleshooting:

  • You must specify the full destination, including the filename. Otherwise the script is not able to compare the files and determine if it is necessary to copy the file (in cases where ifDifferent is specified).
  • When copying a file to a user’s computer, the dynamic wildcards makes it very easy to copy files locations that vary from user to user, for example, the user’s desktop.

Example: Copy \\domain\netlogon\lmhost to %SystemRoot%\System32\drivers\etc\lmhost. This will only copy lmhost file when it is changed on the server. Note the user of the wildcard %SystemRoot% which points the user’s Windows directory.

<actionSet>
    <filterSet>
        <!-- filters go here -->
    </filterSet>
    <actions>
        <copyFile source="\\domain\netlogon\lmhost" destination="%SystemRoot%\System32\drivers\etc\" />
    </actions>
</actionSet>

Example: Force copy of \\domain\netlogon\lmhost to %SystemRoot%\System32\drivers\etc\lmhost. This will copy lmhost file every time the script is executed. Note the user of the wildcard %SystemRoot% which points the user’s Windows directory. 

<actionSet>
    <filterSet>
        <!-- filters go here -->
    </filterSet>
    <actions>
        <copyFile source="\\domain\netlogon\lmhost" destination="%SystemRoot%\System32\drivers\etc\" option="alwaysCopy" />
    </actions>
</actionSet>

Execute a program in the background

With the executeInBackground action you can start execution of program and continue with the rest of the script.

Attributes:

  • executable (required)

Notes / troubleshooting:

  • The program specified in the executable attribute will continue to run in the background in parallel with the script, as a background process, e.g. if you choose to start notepad.exe, Notepad will not be displayed, but you will be able to see it in the processes list in the Task Manager.
  • It is possible to define parameters to the executable.

Example: Opened %SystemDrive%\someFile.txt with notepad (this is a somewhat silly example, since Notepad would not be visible).

<actionSet>
    <filterSet>
        <!-- filters go here -->
    </filterSet>
    <actions>
        <executeInBackground executable="notepad.exe %SystemDrive%\someFile.txt" />
    </actions>
</actionSet>

Execute a program and wait for it to finish

With the executeAndWait action you can start execution of program and pause the script while you wait for the program to finish.

Attributes:

  • executable (required)

Notes / troubleshooting:

  • The program runs as background process, e.g. if you choose to start notepad.exe, Notepad will not be displayed, but you will be able to see it in the processes list in the Task Manager.
  • It is possible to define parameters to the executable.

Example: Opened %SystemDrive%\someFile.txt with notepad (this is a somewhat silly example, since Notepad would not be visible).

<actionSet>
    <filterSet>
        <!-- filters go here -->
    </filterSet>
    <actions>
        <executeAndWait executable="notepad.exe %SystemDrive%\someFile.txt" />
    </actions>
</actionSet>

Map a UNC path to a drive letter

With the mapDrive action you can map an UNC path to a drive letter. If only one letter is specified in the drive attribute, the mapDrive action will first try to un-map any existing mappings to that drive letter, and then proceed with the mapping. If more than one drive letter is specified, the mapDrive action will map the specified UNC to the first free drive letter. If none of the specified drive letters are free, the mapDrive action will print an error message.

Attributes:

  • drive (required)
  • unc (required)
  • persistent (default = false)

Notes / troubleshooting:

  • The script do not create a persistent mapping (i.e. net use * \\xxx\yyy /P:Y)

Example: Map \\FileServer\share to x:.

<actionSet>
    <filterSet>
        <!-- filters go here -->
    </filterSet>
    <actions>
        <mapDrive drive="x" unc="\\FileServer\share" />
    </actions>
</actionSet>

Example: Try to map \\FileServer\share to y:, if y: is already in use, try to map with x:, if x: is also in use, try with w:. If none of the specified drive letters are available, an error message is printed to the user.

<actionSet>
    <filterSet>
        <!-- filters go here -->
    </filterSet>
    <actions>
        <mapDrive drive="yxw" unc="\\FileServer\share" />
    </actions>
</actionSet>

Example: Create a persistent mapping of \\FileServer\share to x:.

<actionSet>
    <filterSet>
        <!-- filters go here -->
    </filterSet>
    <actions>
        <mapDrive drive="x" unc="\\FileServer\share" persistent="true" />
    </actions>
</actionSet>

Set the users default printer

With the setDefaultPrinter action you can assign a users default printer. The only requirement is that the printer is already installed on the user’s computer when the action is executed.

Attributes:

  • unc (required)

Notes / troubleshooting:

Example: Set \\PrinterServer\hp as the users default printer.

<actionSet>
    <filterSet>
        <!-- filters go here -->
    </filterSet>
    <actions>
        <setDefaultPrinter unc="\\PrinterServer\hp" />
    </actions>
</actionSet>

Dynamic wildcards

The wildcard names should convey what they are wildcards for. If there is any doubt, feel free to post a comment and I will clarify.

%Computername%
Name of the computer the user is logging on to.
%Username%
Current users username.
%Domain%
%LogonServer%
%AllUsersDesktop%
%AllUsersStartMenu%
%AllUsersPrograms%
%AllUsersStartup%
%Desktop%
%Favorites%
%Fonts%
%MyDocuments%
%NetHood%
%PrintHood%
%Programs%
%Recent%
%SendTo%
%StartMenu%
%Startup%
%SystemDrive%
%SystemRoot%
%Templates%

Comments are closed.