Command-Line Mailbox Creation

A convenient method for a common task

Almost every Exchange administrator creates mailboxes at some point. In Exchange Server 5.5, you can use a variety of methods for creating accounts. Small companies might use Microsoft Exchange Administrator, and large companies might rely on third-party utilities. However, scripting gives you the best options. Let's look at how you can use a script to create Exchange mailboxes in Exchange 5.5. Because Exchange 2000 Server works differently, you must use a different technique in that Exchange version.

Why Script?
Although Exchange 2000 is available, administrators still create many thousands of mailboxes in Exchange Server 5.5. Creating mailboxes with a script is a simple and often overlooked technique. Scripting offers several advantages. First, scripting ensures that you create mailboxes the same way every time. Second, by using a script, you minimize the possibility for administrator error. For example, it's easy to skip a field when you're using a GUI, whereas a script can verify fields before it creates the mailbox. Third, a script helps you adhere to company mailbox standards (e.g., naming conventions). Fourth, you eliminate reliance on the Exchange Administrator program GUI for simple tasks and gain some advantages, such as access to five attributes not available in the GUI. Finally, scripting gives you a great deal of flexibility. Changing an area code or SMTP address for thousands of mailboxes becomes a less daunting procedure with scripting.

To automate mailbox creation, you need to create an import file, then use a batch file to create a new mailbox. However, you must first decide what you want to include in the import file.

Making an Import File
Import files contain, at a minimum, one line containing header information and one line containing data about objects such as mailboxes, distribution lists (DLs), or custom recipients. The header information consists of properties found in the schema. (The schema defines the attributes associated with objects and the values associated with attributes.) For a quick look at header information, open Exchange Administrator and click Tools, Directory Export. Click Export File, and enter the name testexport.csv. Save the file in a temporary directory so that you can delete it later, then click Export. Exporting won't remove or delete information from the directory. Open the file in Notepad or Microsoft Excel to see an example of a Directory Export file, such as the file Figure 1 shows.

The data you choose to include in the import file depends on the information in the header. In other words, you can import fax number information only if the Fax Number attribute is in the header. A mailbox can hold more than 60 attributes with a default Exchange installation, but you don't need all the attributes to create a new mailbox. At a minimum, the header information for a mailbox contains the Obj-Class, Directory Name, and Home-Server attributes; however, that information isn't sufficient for a business mailbox. An import file usually contains many more attributes, such as Primary Account, which you use to link a Windows NT user or group and its permissions to a mailbox. Therefore, you need to select the attributes you want to include in the import file.

Selecting Attributes
The Directory Export method, which I explained in the previous section, exports only a fraction of the attributes available. There are two ways to display the entire list of attributes. The first method is to use the Header program, which you can obtain from the Microsoft BackOffice Resource Kit. Header is a simple utility that exposes directory attributes by object. Header lets you generate a Comma Separated Value (CSV) attribute file for mailboxes, DLs, and other objects.

The second method for viewing attributes is to use Microsoft's mailbox.csv file, which contains a ready-made comma-delimited list of mailbox attributes. The Microsoft article "XADM: Sample CSVs Not Included on Exchange Server 5.0 or 5.5 CD" (http://support.microsoft.com/support/kb/articles/q169/7/61.asp) explains where you can download mailbox.csv, .csv files for DLs, and other sample .csv files.

From the comprehensive list of attributes, you determine which attributes you want when you create an account. With the .csv file of all the mailbox attributes, you're ready to export all the mailbox information from the directory. From Exchange Administrator, use the same directory export procedure, but this time, select the Header or mailbox.csv file as the export file. When you click Export, Exchange reads the attributes from the .csv file and dumps mailbox information for each attribute from the directory to the .csv file. Exchange renames the original file with the new extension .c01.

Open the newly populated .csv file in a spreadsheet program such as Excel. Go through the headers to determine the attributes to use for importing new mailboxes. To make the fields easier to view in Excel, select Format, Column, AutoFit Selection. When you find the attributes you don't need, delete those columns from the spreadsheet until you've narrowed the list down to your final choices. When the spreadsheet displays only the needed attributes, save the spreadsheet in CSV format. Now you can use attributes from this import file and a script to create a mailbox.

Scripting a New Mailbox
After you've selected the attributes to use in the new mailboxes, you write a short batch file to incorporate command-line parameters and create a new mailbox. For example, I created newmb.bat, which Listing 1 shows. I started each section of the script with a REM comment. The first section of the script echoes the contents of the header information to a file with the user's name. When you write your script, the header must contain the attributes you selected. The second section contains the information for each attribute in the header.

To demonstrate how this batch file works, let's create a mailbox for new user Jennifer Hansen. Jennifer already has a domain account, jenniferh, in DomainA. Jennifer's domain account will be the primary account for the mailbox.

The variable %1 represents the username in the domain account, %2 represents the user's first name, and %3 represents the user's last name. The script uses the variables to customize the import file. You provide the values for these variables when you launch the script from the command-shell window. In this example, you would type

newmb.bat jenniferh Jennifer Hansen

on the command line to launch the script and provide the three variable values. (For more information about using environmental variables to temporarily hold a value, see Dick Lewis, "Shell Scripting 101, Lesson 3," http://www.winscriptingsolutions.com, InstantDoc ID 20142.)

The first two sections in the script use the %1, %2, and %3 variables to create a customized, text-based import file from the generic CSV-based import file you created earlier. The script names the customized import file based on the username (in this case, jenniferh.txt) and saves the file to \adminhostscripts. (You can customize the location by changing this path in the script.) In the customized import file, attributes containing no information display with two consecutive commas in the data field. The first two sections create the import file and save it to \adminhostscripts. The import file is named jenniferh.txt based on the username variable.

After the first two sections of the script create the customized import file, the last section in the script uses that file to create an Exchange mailbox. As callout A in Listing 1 shows, the script uses the Exchange admin utility to create the mailbox.

The /i switch sets admin.exe to import mode so that admin.exe can import the new mailbox. If you changed the location in which you saved this file, you need to replace \adminhostscripts with your directory path. The /d switch designates the server name that contains the directory to update. Thus, you might need to replace exchsrvr with your server's name. For reference, the /? switch describes all the command-line parameters.

When you run admin.exe with /i, Exchange makes several assumptions about how to perform the import. For example, the program makes imports to the Recipients container by default. You can modify defaults by creating an options file and using the /o switch. Figure 2, shows the makeup of an options file and what the import defaults are. In most cases, you don't need to create the options file.

After newmb.bat executes, you'll have a new mailbox with six fields: first name, last name, alias, display name, primary NT account (assuming the username jenniferh exists), and multiple email addresses. For more information about how to write scripts that create new user accounts, see "Take Command of Your Management Tasks," http://www.win2000mag.com, InstantDoc ID 16426. The Microsoft article "XADM: Description of Directory Export/Import Event IDs" (http://support.microsoft.com/support/kb/articles/q184/5/32.asp) provides a list of error codes related to imports.

Better Late than Never
Creating mailboxes from the command line is nothing new to Exchange 5.5. However, many administrators continue to rely on the GUI for mailbox creation. Scripting mailboxes promotes consistency, reduces errors, and maintains standards. Possibly the best benefit of scripting is the time you save compared with manually creating mailboxes with the GUI. Try importing mailboxes in your test lab to get a feel for how easy the process is. You'll wonder why you ever created mailboxes any other way.