================================================================= MHS MAILBOX CONVERSION UTILITY 07Aug1995 ================================================================= -------------------------------- CONTENTS -------------------------------- INTRODUCTION PREREQUISITES TO RUN THE MHS MCU INSTALLING THE MHS MCU RUNNING THE MHS MCU ADDITIONAL INFORMATION ================================================================= INTRODUCTION ================================================================= The GroupWise Mailbox Conversion Utility for MHS (MHS MCU) is a user migration tool that converts MHS user mailboxes to GroupWise via the GroupWise API Gateway. Conversions from Da Vinci, BeyondMail, and FirstMail systems are supported. The MHS MCU can also convert e-mail from other SMF mail clients that store messages as individual SMFv70 and SMFv71 format files. ================================================================= PREREQUISITES TO RUN THE MHS MCU ================================================================= * The GroupWise API Gateway must be installed and running in the GroupWise system to which foreign users will migrate. To purchase the GroupWise API Gateway, call Novell at 1-800-861-2507. To install and set up the gateway, refer to the GroupWise API Gateway Guide. * Before migrating an MHS user's mailbox to GroupWise, you must first define the user in your GroupWise system. See the GroupWise Administration Guide for more information about creating GroupWise users. ================================================================= INSTALLING THE MHS MCU ================================================================= The MHS MCU is distributed on disk as a self-extracting ZIP file named UNZIPMCU.EXE. To install MHS MCU, 1 Create a directory for the program on your hard drive or on a network server. 2 Insert the disk labeled Mailbox Conversion Utility for MHS into a floppy drive. 3 Copy UNZIPMCU.EXE from the Mailbox Conversion Utility disk to the directory you created in step 1. 4 From the directory where UNZIPMCU.EXE is located, enter UNZIPMCU -D to unzip the program, documentation, and sample files. For example: md c:\mcu copy a:\unzipmcu.exe c:\mcu cd \mcu unzipmcu -d ================================================================= RUNNING THE MHS MCU ================================================================= When you execute the MHS MCU with the required parameters, it first converts foreign mailboxes to SMF v71 message format. These SMF messages are then converted to API format and placed in the appropriate GroupWise API Gateway input directories. The GroupWise API Gateway and GroupWise servers then complete the migration. Messages coming into GroupWise are placed in single-level folders that are created as necessary to approximate the hierarchy of the folders in the original mail system. (For more information about how the folders are created, see Additional Information at the end of this guide.) All messages retain their original delivery date and opened status in GroupWise, but no statuses are returned to the foreign mail system. -------------------------------- USING STARTUP PARAMETERS -------------------------------- The MHS MCU is a batch-mode DOS program that accepts parameter input in the following form: /keyword-value You can use parameters in any of the following ways: * Command line * Parameter file * Both command line and parameter file For example, in a batch file, you could place common or "global" parameters in a parameter file and then use additional command line parameters for user-specific options. If you use a parameter file, you must specify the name and location of the file with the ParmFile keyword, as shown in the following table. You may also need to use the parameter file option to overcome the DOS command line length limitation. The following table summarizes the parameters available for MHS MCU. Keywords may be abbreviated to include as few characters as are capitalized. For example, "TOuser" may be abbreviated as "to", and "Target" may be entered as "t". Keyword R=Required Description and Example O=Optional TOuser R GroupWise user name in the form domain.po.user. The user must already exist in the GroupWise system. For example, /to-hq.advertising.georgia If the user ID is unique in the GroupWise system and if you don't want to preserve draft and outbox messages, you can specify the user ID only (for example, georgia) and not the fully qualified name (headquarters.advertising.georgia). Source R User's mail directory to be converted. This varies depending on the type of mailbox being converted. For example, for Da Vinci, the parameter might be /s-m:\davinci\users Note: The DaVinci usage of this para- meter has changed. The "\USERS" portion of the source path is no longer added automatically. Target R GroupWise API Gateway home directory. For example, /t-d:\domain\wpgate\api Parmfile O The path to a parameter file. For example, /p-d:\work\setfile2 The parameter file must be in DOS text form and may contain several parameters, each on a separate line, as in Source-s:\davinci\users Target-d:\ngw41\wpgate\api Mailtype-davinci Work-c:\temp\work Note: In the parameter file, forward slashes (/) in front of the keywords are optional. Attachments O Selects the attachment export option, with the following syntax: No | Yes | [K | M] "No", the default, indicates that no attachments are to be migrated. "Yes" indicates that all attachments, regardless of size, are to be migrated. indicates the largest allowable attachment size in kilobytes (K) or megabytes (M) that is to be migrated. For example, /a-yes or /a-10k Folders O Limits migration to items in the specified folder(s), with the following syntax. [ROOT], substring1, substring2, ... For example, /fo-internal, private, meetings By default, MHS MCU does not migrate items located in folders named Trash, Wastebasket, or in any folder with the string "nomigrat" in its name. (The exclusions are case-insensitive.) Use of the Folders option overrides this default and causes MHS MCU to migrate only those items in folders whose names contain any of the named substrings. (For example, /Folders-trash, waste, nomigrat would cause MHS MCU to get ONLY items in the folders normally excluded.) A special keyword, root, is used to indicate the root mail folder; the specification /Folders-root would limit the mail being migrated to those items found in the root folder. Fromuser O/R MHS (source) user name. This parameter is required only for DaVinci migration. /f-georgia Loglevel O Log level of messages written to log file. Options are Normal, Off, Verbose, or Diagnose. For example, /l-verbose A logging level of Normal or higher is required for logging. With LogLevel- Off, only command syntax and parameter input errors are displayed. LOGType O Specifies log file naming preference. Options are PerUser or Single. PerUser produces a file for each user (such as GEORGIA.LOG), while the Single option produces a single log file (such as MCU.LOG) For example, /logt-single Mailtype O MHS mail format. Options are SMF71, BeyondMail, Da Vinci, or FirstMail. For example, /m-davinci Work O Intermediate output directory. If not specified, the default is to the current directory. The MSG and ATT subdirectories and files will be created at this location. For example, /w-c:\temp PReserveread O Preserve read (opened) status. If specified, unopened messages will be moved to the root folder of the Inbox and will be treated as new, unread messages. The default behavior is to treat read and unread messages similarly. For example, /preserve or /pr Debug O Writes all SMF headers as API MHF comments and sets LogLevel-Verbose. For example, /debug or /d NoCleanUp O Retains intermediate \MSG and \ATT files. For the MailType-SMF71, this is the default. For example, /nocleanup or /n -------------------------------- CONVERTING A DA VINCI MAILBOX -------------------------------- To migrate a Da Vinci user to GroupWise, complete the following: 1 Send seed message to the user whose messages are to be converted. Da Vinci messages are stored in the user mailbox (database) in an encrypted SMF v71 format. MHS MCU runs an internal conversion routine that locates and decrypts a seed message. The conversion routine then extracts messages to the work directory (specified with the Work startup parameter) in SMF v71 format. After completing the Da Vinci conversion/extraction, MHS MCU proceeds with the normal SMF v71 to API message header file conversion. IMPORTANT: The seed message must be mailed to the Da Vinci user, and the user must load the message in the Da Vinci client before you can succesfully run MHS MCU. To create the seed message, send a message with the file DVSEED.ATT as an attachment. This file is provided with the MHS MCU utility in the SAMPLES directory. 2 Have the user load the seed message into the Da Vinci client. 3 Create or edit the MCU parameter file. The following sample file, named DV.CFG, is available in the SAMPLES directory. source-s:\davinci\users target-d:\ngw41\wpgate\api mailtype-davinci work-c:\temp\work 4 Run MCU. For example, mcu /to=gwuser /from=dvuser /parm=dv.cfg -------------------------------- CONVERTING A FIRSTMAIL MAILBOX -------------------------------- To migrate a FirstMail user to GroupWise, complete the following: 1 Locate the user's mailbox directory. FirstMail messages are stored under folders in SMF v71 format. The mailbox directory location may be the default MHS directory or some other location specified by the user. You must find out what this directory is and specify it in the Source- parameter. Since the full mailbox path is required, you don't need to provide the MHS user name with the FromUser parameter. Since FirstMail lets the user relocate the mailbox to a local drive, you must ensure that the mailbox is moved (or copied) to a location where MHS MCU can access it. By default, the mailbox is located on the user's server in \SYS:\MAIL\xxxxxxxx (where xxxxxxxx is the hexadecimal NetWare user ID). 2 Create or edit the MCU parameter file. The following sample file, named FM.CFG, is available in the SAMPLES directory. target-d:\ngw41\wpgate\api attachments-10k mailtype-firstmail work-c:\temp 3 Run MCU. For example, mcu /touser=gwuser /source-s:\mail\xxxxxxxx /parmfile=fm.cfg -------------------------------- CONVERTING A BEYONDMAIL MAILBOX -------------------------------- To migrate a BeyondMail user to GroupWise, complete the following steps: 1 Export the user's mailbox directory using the BeyondMail EXPORT command. For example, export c:\temp\bmuser\bmuser -u bmuser -all -a2 c:\temp\bmuser For more information, see Using the Export Command below. 2 Create or edit the MCU parameter file. The following sample file, named BM.CFG, is available in the SAMPLES directory. target-d:\ngw41\wpgate\api attachments-1m mailtype-beyondmail work-c:\temp\work 3 Run MCU. For example, mcu /to=gwuser /source-c:\temp\bmuser /from-bmuser /parm=bm.cfg Using the Export Command -------------------------------- BeyondMail messages are stored by folder in either encrypted or unencrypted non-SMF v71 format. You must export messages prior to migration using the BeyondMail backup utility EXPORT. This places the user's messages in a format that MHS MCU can process. The format for the EXPORT command is: export [-u loginName] -all -a2 where is the path and filename for the exported messages. For use with MHS MCU, the path portion of this parameter must be MHS MCU's Source parameter value; the filename portion must be the MHS MCU FromUser parameter value. LoginName is required to export a mailbox for a user other than the currently logged in user. is the path into which attachments will be exported. For use with MHS MCU, this must match MHS MCU's Source parameter value. For more information about the EXPORT utility, refer to the BeyondMail Administration Reference. ----------------------------------- CONVERTING SMF FORMAT MESSAGE FILES ----------------------------------- To convert e-mail from SMF mail clients that store messages as individual SMFv70 of SMFv71 format files, complete the following steps: 1 Locate the user's mailbox directories. 2 Copy the user's mail files to temporary subdirectories. You must copy the SMF message files that will be migrated to a subdirectory named ...\MSG. If attachments will also be migrated to GroupWise, place them in a subdirectory named ...\ATT. In this example, the directories C:\TEMP\MSG and C:\TEMP\ATT are used. The path C:\TEMP is passed to the MCU as the \Source- parameter. IMPORTANT: As the MCU runs, it deletes the files that the \Source parameter points to. Novell recommends that you use the procedure noted in this step to make temporary copies of the files rather than pointing to the originals. 3 Configure the MCU parameter file. For example, if you copied the SMF mail files to the c:\temp\msg and c:\temp\att directories, and if the API gateway home directory is d:\ngw41\wpgate\api, you could create and use a parmfile like the one shown below. In this case, the name of the file is SMF.CFG. mailtype-smf71 source-c:\temp target-d:\ngw41\wpgate\api attachments-yes 4 Run the MCU. For example, if the user's GroupWise ID is CHARLENE, run the following command: mcu /to-charlene /parm-smf.cfg ================================================================= ADDITIONAL INFORMATION ================================================================= -------------------------------- FOLDERS -------------------------------- If the mailbox being migrated to GroupWise has items stored in folders, MHS MCU generates the GroupWise API keyword command FOLDER=xx to import the item. However, since the GroupWise API Gateway can create only single-level folders, the entire folder path from the foreign mailbox is used to generate the new GroupWise folder name. Illegal characters (such as the forward slash (/) used by Da Vinci to delimit folder hierarchies) are translated to underscores (_). The decision to create folders using the full path rather than the final level folder name was based on the need for users to differentiate between items in same-named leaf folders from different hierarchical branches. Once items are migrated to GroupWise, users can rearrange their mail items into a truly hierarchical organization. Folders with no messages in them will not be migrated. Also, unread mail items will always be placed in the root Inbox folder to preserve their unread status. -------------------------------- PARAMETER FILES -------------------------------- You may use the /ParmFile-path option to point to a file containing several startup parameters. For example, /parmfile-d:\work\setfile2 The parameter file must be in DOS text form, with each parameter on a separate line, as in source-s:\davinci\users target-d:\ngw41\wpgate\api mailtype-davinci work-c:\temp\work In the parameter file, forward slashes (/) in front of the keywords are optional. Also, any line beginning with "rem" or "*" is considered a comment and is skipped. -------------------------------- SAMPLE FILES -------------------------------- When you install MHS MCU, several sample batch and parameter files for use with various mail types are copied to the SAMPLES directory. RUNxx.BAT and xx.CFG files are provided for Da Vinci (DV), BeyondMail (BM) and FirstMail (FM).