home *** CD-ROM | disk | FTP | other *** search
/ Network Support Encyclopedia 96-1 / novell-nsepro-1996-1-cd2.iso / download / gw / mhsmcu.exe / UNZIPMCU.EXE / DOC / MCU.TXT
Text File  |  1995-08-14  |  20KB  |  529 lines
  1. =================================================================
  2. MHS MAILBOX CONVERSION UTILITY                          07Aug1995
  3. =================================================================
  4.  
  5. --------------------------------
  6. CONTENTS
  7. --------------------------------
  8.  
  9.      INTRODUCTION
  10.      PREREQUISITES TO RUN THE MHS MCU
  11.      INSTALLING THE MHS MCU
  12.      RUNNING THE MHS MCU
  13.      ADDITIONAL INFORMATION
  14.  
  15.  
  16. =================================================================
  17. INTRODUCTION
  18. =================================================================
  19.  
  20. The GroupWise Mailbox Conversion Utility for MHS (MHS MCU) is a
  21. user migration tool that converts MHS user mailboxes to GroupWise
  22. via the GroupWise API Gateway.  Conversions from Da Vinci,
  23. BeyondMail, and FirstMail systems are supported.  The MHS MCU can
  24. also convert e-mail from other SMF mail clients that store
  25. messages as individual SMFv70 and SMFv71 format files.
  26.  
  27.  
  28. =================================================================
  29. PREREQUISITES TO RUN THE MHS MCU
  30. =================================================================
  31.  
  32.      *  The GroupWise API Gateway must be installed and running
  33.         in the GroupWise system to which foreign users will
  34.         migrate.  To purchase the GroupWise API Gateway, call
  35.         Novell at 1-800-861-2507.  To install and set up the
  36.         gateway, refer to the GroupWise API Gateway Guide.
  37.      *  Before migrating an MHS user's mailbox to GroupWise, you
  38.         must first define the user in your GroupWise system.  See
  39.         the GroupWise Administration Guide for more information
  40.         about creating GroupWise users.
  41.  
  42.  
  43. =================================================================
  44. INSTALLING THE MHS MCU
  45. =================================================================
  46.  
  47. The MHS MCU is distributed on disk as a self-extracting ZIP file
  48. named UNZIPMCU.EXE.  To install MHS MCU,
  49.  
  50.      1    Create a directory for the program on your hard drive
  51.           or on a network server.
  52.  
  53.      2    Insert the disk labeled Mailbox Conversion Utility for
  54.           MHS into a floppy drive.
  55.  
  56.      3    Copy UNZIPMCU.EXE from the Mailbox Conversion Utility
  57.           disk to the directory you created in step 1.
  58.  
  59.      4    From the directory where UNZIPMCU.EXE is located, enter
  60.           UNZIPMCU -D to unzip the program, documentation, and
  61.           sample files.
  62.  
  63. For example:
  64.  
  65.      md c:\mcu
  66.      copy a:\unzipmcu.exe c:\mcu
  67.      cd \mcu
  68.      unzipmcu -d
  69.  
  70.  
  71. =================================================================
  72. RUNNING THE MHS MCU
  73. =================================================================
  74.  
  75. When you execute the MHS MCU with the required parameters, it
  76. first converts foreign mailboxes to SMF v71 message format. 
  77. These SMF messages are then converted to API format and placed in
  78. the appropriate GroupWise API Gateway input directories.  The
  79. GroupWise API Gateway and GroupWise servers then complete the
  80. migration.
  81.  
  82. Messages coming into GroupWise are placed in single-level folders
  83. that are created as necessary to approximate the hierarchy of the
  84. folders in the original mail system.  (For more information about
  85. how the folders are created, see Additional Information at the
  86. end of this guide.) All messages retain their original delivery
  87. date and opened status in GroupWise, but no statuses are returned
  88. to the foreign mail system.
  89.  
  90. --------------------------------
  91. USING STARTUP PARAMETERS
  92. --------------------------------
  93.  
  94. The MHS MCU is a batch-mode DOS program that accepts parameter
  95. input in the following form:
  96.  
  97.      /keyword-value
  98.  
  99. You can use parameters in any of the following ways:
  100.  
  101.      *  Command line
  102.      *  Parameter file
  103.      *  Both command line and parameter file
  104.  
  105. For example, in a batch file, you could place common or "global"
  106. parameters in a parameter file and then use additional command
  107. line parameters for user-specific options.
  108.  
  109. If you use a parameter file, you must specify the name and
  110. location of the file with the ParmFile keyword, as shown in the
  111. following table.  You may also need to use the parameter file
  112. option to overcome the DOS command line length limitation.
  113.  
  114. The following table summarizes the parameters available for MHS
  115. MCU. Keywords may be abbreviated to include as few characters as
  116. are
  117. capitalized. For example, "TOuser" may be abbreviated as "to", and 
  118. "Target" may be entered as "t".
  119.  
  120.  
  121. Keyword       R=Required  Description and Example
  122.               O=Optional
  123.  
  124. TOuser        R           GroupWise user name in the form
  125.                           domain.po.user.  The user must already
  126.                           exist in the GroupWise system.  For
  127.                           example,
  128.  
  129.                           /to-hq.advertising.georgia
  130.  
  131.                           If the user ID is unique in the
  132.                           GroupWise system and if you don't want
  133.                           to preserve draft and outbox messages,
  134.                           you can specify the user ID only (for
  135.                           example, georgia) and not the fully
  136.                           qualified name
  137.                           (headquarters.advertising.georgia).
  138.  
  139. Source        R           User's mail directory to be converted.
  140.                           This varies depending on the type of
  141.                           mailbox being converted.  For example,
  142.                           for Da Vinci, the parameter might be
  143.  
  144.                           /s-m:\davinci\users
  145.  
  146.                           Note: The DaVinci usage of this para-
  147.                           meter has changed. The "\USERS" portion 
  148.                           of the source path is no longer added 
  149.                           automatically.
  150.  
  151. Target        R           GroupWise API Gateway home directory.
  152.                           For example,
  153.  
  154.                           /t-d:\domain\wpgate\api
  155.  
  156. Parmfile      O           The path to a parameter file.  For
  157.                           example,
  158.  
  159.                           /p-d:\work\setfile2
  160.  
  161.                           The parameter file must be in DOS text
  162.                           form and may contain several 
  163.                           parameters, each on a separate line, 
  164.                           as in
  165.  
  166.                           Source-s:\davinci\users
  167.                           Target-d:\ngw41\wpgate\api
  168.                           Mailtype-davinci
  169.                           Work-c:\temp\work
  170.  
  171.                           Note: In the parameter file, forward
  172.                           slashes (/) in front of the keywords
  173.                           are optional.
  174.  
  175. Attachments   O           Selects the attachment export option, 
  176.                           with the following syntax:
  177.  
  178.                           No | Yes | <max size>[K | M]
  179.  
  180.                           "No", the default, indicates that no
  181.                           attachments are to be migrated.
  182.  
  183.                           "Yes" indicates that all attachments,
  184.                           regardless of size, are to be migrated.
  185.  
  186.                           <max size> indicates the largest
  187.                           allowable attachment size in kilobytes
  188.                           (K) or megabytes (M) that is to be
  189.                           migrated.  For example,
  190.  
  191.                           /a-yes   or   /a-10k
  192.  
  193. Folders       O           Limits migration to items in the
  194.                           specified folder(s), with the following
  195.                           syntax.
  196.  
  197.                           [ROOT], substring1, substring2, ...
  198.  
  199.                           For example,
  200.  
  201.                           /fo-internal, private, meetings
  202.  
  203.                           By default, MHS MCU does not migrate
  204.                           items located in folders named Trash,
  205.                           Wastebasket, or in any folder with the
  206.                           string "nomigrat" in its name.  (The
  207.                           exclusions are case-insensitive.) Use
  208.                           of the Folders option overrides this
  209.                           default and causes MHS MCU to migrate
  210.                           only those items in folders whose names
  211.                           contain any of the named substrings.
  212.                           (For example, /Folders-trash, waste,
  213.                           nomigrat would cause MHS MCU to get
  214.                           ONLY items in the folders normally
  215.                           excluded.) A special keyword, root, is
  216.                           used to indicate the root mail folder;
  217.                           the specification /Folders-root would
  218.                           limit the mail being migrated to those
  219.                           items found in the root folder.
  220.  
  221. Fromuser      O/R         MHS (source) user name. This parameter
  222.                           is required only for DaVinci migration.
  223.  
  224.                           /f-georgia
  225.  
  226. Loglevel      O           Log level of messages written to log
  227.                           file.  Options are Normal, Off, 
  228.                           Verbose, or Diagnose.  For example,
  229.  
  230.                           /l-verbose
  231.  
  232.                           A logging level of Normal or higher is
  233.                           required for logging.  With LogLevel-
  234.                           Off, only command syntax and parameter 
  235.                           input errors are displayed.
  236.  
  237. LOGType       O           Specifies log file naming preference.
  238.                           Options are PerUser or Single.  PerUser
  239.                           produces a file for each user (such as
  240.                           GEORGIA.LOG), while the Single option
  241.                           produces a single log file (such as
  242.                           MCU.LOG) For example,
  243.  
  244.                           /logt-single
  245.  
  246. Mailtype      O           MHS mail format.  Options are SMF71,
  247.                           BeyondMail, Da Vinci, or FirstMail. 
  248.                           For example,
  249.  
  250.                           /m-davinci
  251.  
  252. Work          O           Intermediate output directory. If 
  253.                           not specified, the default is to 
  254.                           the current directory. The MSG and
  255.                           ATT subdirectories and files will 
  256.                           be created at this location.
  257.                           For example,
  258.  
  259.                           /w-c:\temp
  260.  
  261. PReserveread  O           Preserve read (opened) status. If 
  262.                           specified, unopened messages will 
  263.                           be moved to the root folder of the
  264.                           Inbox and will be treated as new, 
  265.                           unread messages. The default 
  266.                           behavior is to treat read and 
  267.                           unread messages similarly.
  268.                           For example,
  269.  
  270.                           /preserve   or /pr
  271.  
  272. Debug         O           Writes all SMF headers as API MHF
  273.                           comments and sets LogLevel-Verbose.
  274.                           For example, 
  275.  
  276.                           /debug      or /d
  277.  
  278. NoCleanUp     O           Retains intermediate <Work>\MSG and
  279.                           \ATT files.  For the MailType-SMF71,
  280.                           this is the default. For example,
  281.  
  282.                           /nocleanup  or /n
  283.  
  284.  
  285. --------------------------------
  286. CONVERTING A DA VINCI MAILBOX
  287. --------------------------------
  288.  
  289. To migrate a Da Vinci user to GroupWise, complete the following:
  290.  
  291.      1    Send seed message to the user whose messages are to be
  292.           converted.
  293.  
  294.      Da Vinci messages are stored in the user mailbox (database)
  295.      in an encrypted SMF v71 format.  MHS MCU runs an internal
  296.      conversion routine that locates and decrypts a seed message. 
  297.      The conversion routine then extracts messages to the work
  298.      directory (specified with the Work startup parameter) in SMF
  299.      v71 format.  After completing the Da Vinci
  300.      conversion/extraction, MHS MCU proceeds with the normal SMF
  301.      v71 to API message header file conversion.
  302.  
  303.      IMPORTANT:  The seed message must be mailed to the Da Vinci
  304.      user, and the user must load the message in the Da Vinci
  305.      client before you can succesfully run MHS MCU.  To create
  306.      the seed message, send a message with the file DVSEED.ATT as
  307.      an attachment.  This file is provided with the MHS MCU
  308.      utility in the SAMPLES directory.
  309.  
  310.      2    Have the user load the seed message into the Da Vinci
  311.           client.
  312.  
  313.      3    Create or edit the MCU parameter file.
  314.  
  315.      The following sample file, named DV.CFG, is available in the
  316.      SAMPLES directory.
  317.  
  318.      source-s:\davinci\users
  319.      target-d:\ngw41\wpgate\api
  320.      mailtype-davinci
  321.      work-c:\temp\work
  322.  
  323.      4    Run MCU.
  324.  
  325.      For example,
  326.  
  327.      mcu /to=gwuser /from=dvuser /parm=dv.cfg
  328.  
  329. --------------------------------
  330. CONVERTING A FIRSTMAIL MAILBOX
  331. --------------------------------
  332.  
  333. To migrate a FirstMail user to GroupWise, complete the following:
  334.  
  335.      1    Locate the user's mailbox directory.
  336.  
  337.      FirstMail messages are stored under folders in SMF v71
  338.      format.  The mailbox directory location may be the default
  339.      MHS directory or some other location specified by the user. 
  340.      You must find out what this directory is and specify it in
  341.      the Source-<path> parameter.  Since the full mailbox path is
  342.      required, you don't need to provide the MHS user name with
  343.      the FromUser parameter.
  344.  
  345.      Since FirstMail lets the user relocate the mailbox to a
  346.      local drive, you must ensure that the mailbox is moved (or
  347.      copied) to a location where MHS MCU can access it.  By
  348.      default, the mailbox is located on the user's server in
  349.      \SYS:\MAIL\xxxxxxxx (where xxxxxxxx is the hexadecimal
  350.      NetWare user ID).
  351.  
  352.      2    Create or edit the MCU parameter file.
  353.  
  354.      The following sample file, named FM.CFG, is available in the
  355.      SAMPLES directory.
  356.  
  357.      target-d:\ngw41\wpgate\api
  358.      attachments-10k
  359.      mailtype-firstmail
  360.      work-c:\temp
  361.  
  362.      3    Run MCU.
  363.  
  364.      For example,
  365.  
  366.      mcu /touser=gwuser /source-s:\mail\xxxxxxxx /parmfile=fm.cfg
  367.  
  368. --------------------------------
  369. CONVERTING A BEYONDMAIL MAILBOX
  370. --------------------------------
  371.  
  372. To migrate a BeyondMail user to GroupWise, complete the following
  373. steps:
  374.  
  375.      1    Export the user's mailbox directory using the
  376.           BeyondMail EXPORT command.
  377.  
  378.      For example,
  379.  
  380.      export c:\temp\bmuser\bmuser -u bmuser -all -a2
  381.      c:\temp\bmuser
  382.  
  383.      For more information, see Using the Export Command below.
  384.  
  385.      2    Create or edit the MCU parameter file.
  386.  
  387.      The following sample file, named BM.CFG, is available in the
  388.      SAMPLES directory.
  389.  
  390.      target-d:\ngw41\wpgate\api
  391.      attachments-1m
  392.      mailtype-beyondmail
  393.      work-c:\temp\work
  394.  
  395.      3    Run MCU.
  396.  
  397.      For example,
  398.  
  399.      mcu /to=gwuser /source-c:\temp\bmuser /from-bmuser
  400.      /parm=bm.cfg
  401.  
  402. Using the Export Command
  403. --------------------------------
  404.  
  405. BeyondMail messages are stored by folder in either encrypted or
  406. unencrypted non-SMF v71 format.  You must export messages prior
  407. to migration using the BeyondMail backup utility EXPORT.  This
  408. places the user's messages in a format that MHS MCU can process. 
  409. The format for the EXPORT command is:
  410.  
  411.      export <outpath>[-u loginName] -all -a2 <attpath>
  412.  
  413. where <outpath> is the path and filename for the exported
  414. messages.  For use with MHS MCU, the path portion of this
  415. parameter must be MHS MCU's Source parameter value; the filename
  416. portion must be the MHS MCU FromUser parameter value.
  417.  
  418. LoginName is required to export a mailbox for a user other than
  419. the currently logged in user.
  420.  
  421. <attpath> is the path into which attachments will be exported. 
  422. For use with MHS MCU, this must match MHS MCU's Source parameter
  423. value.
  424.  
  425. For more information about the EXPORT utility, refer to the
  426. BeyondMail Administration Reference.
  427.  
  428. -----------------------------------
  429. CONVERTING SMF FORMAT MESSAGE FILES
  430. -----------------------------------
  431.  
  432. To convert e-mail from SMF mail clients that store messages as
  433. individual SMFv70 of SMFv71 format files, complete the following
  434. steps:
  435.  
  436.      1    Locate the user's mailbox directories.
  437.  
  438.      2    Copy the user's mail files to temporary subdirectories.
  439.  
  440.      You must copy the SMF message files that will be migrated to
  441.      a subdirectory named ...\MSG.  If attachments will also be
  442.      migrated to GroupWise, place them in a subdirectory named
  443.      ...\ATT.
  444.  
  445.      In this example, the directories C:\TEMP\MSG and C:\TEMP\ATT
  446.      are used.  The path C:\TEMP is passed to the MCU as the
  447.      \Source- parameter.
  448.  
  449.      IMPORTANT:  As the MCU runs, it deletes the files that the
  450.      \Source parameter points to.  Novell recommends that you use
  451.      the procedure noted in this step to make temporary copies of
  452.      the files rather than pointing to the originals.
  453.  
  454.      3    Configure the MCU parameter file.
  455.  
  456.      For example, if you copied the SMF mail files to the
  457.      c:\temp\msg and c:\temp\att directories, and if the API
  458.      gateway home directory is d:\ngw41\wpgate\api, you could
  459.      create and use a parmfile like the one shown below. In this
  460.      case, the name of the file is SMF.CFG.
  461.  
  462.      mailtype-smf71
  463.      source-c:\temp
  464.      target-d:\ngw41\wpgate\api
  465.      attachments-yes
  466.  
  467.      4    Run the MCU.
  468.  
  469.      For example, if the user's GroupWise ID is CHARLENE, run the
  470.      following command:
  471.  
  472.      mcu /to-charlene /parm-smf.cfg
  473.  
  474.  
  475. =================================================================
  476. ADDITIONAL INFORMATION
  477. =================================================================
  478.  
  479. --------------------------------
  480. FOLDERS
  481. --------------------------------
  482.  
  483. If the mailbox being migrated to GroupWise has items stored in
  484. folders, MHS MCU generates the GroupWise API keyword command
  485. FOLDER=xx to import the item.  However, since the GroupWise API
  486. Gateway can create only single-level folders, the entire folder
  487. path from the foreign mailbox is used to generate the new
  488. GroupWise folder name.  Illegal characters (such as the forward
  489. slash (/) used by Da Vinci to delimit folder hierarchies) are
  490. translated to underscores (_).  The decision to create folders
  491. using the full path rather than the final level folder name was
  492. based on the need for users to differentiate between items in
  493. same-named leaf folders from different hierarchical branches. 
  494. Once items are migrated to GroupWise, users can rearrange their
  495. mail items into a truly hierarchical organization.
  496.  
  497. Folders with no messages in them will not be migrated.  Also,
  498. unread mail items will always be placed in the root Inbox folder
  499. to preserve their unread status.
  500.  
  501. --------------------------------
  502. PARAMETER FILES
  503. --------------------------------
  504.  
  505. You may use the /ParmFile-path option to point to a file
  506. containing several startup parameters.  For example,
  507.  
  508.      /parmfile-d:\work\setfile2
  509.  
  510. The parameter file must be in DOS text form, with each parameter
  511. on a separate line, as in
  512.  
  513.      source-s:\davinci\users
  514.      target-d:\ngw41\wpgate\api
  515.      mailtype-davinci
  516.      work-c:\temp\work
  517.  
  518. In the parameter file, forward slashes (/) in front of the
  519. keywords are optional.  Also, any line beginning with "rem" or
  520. "*" is considered a comment and is skipped.
  521.  
  522. --------------------------------
  523. SAMPLE FILES
  524. --------------------------------
  525.  
  526. When you install MHS MCU, several sample batch and parameter
  527. files for use with various mail types are copied to the SAMPLES
  528. directory.  RUNxx.BAT and xx.CFG files are provided for Da Vinci
  529. (DV), BeyondMail (BM) and FirstMail (FM).