Upgrading mail files with the mail conversion utility

When you upgrade users' mail files to the current Notes® mail template or to the iNotes® template, you can upgrade one file at a time or use the mail conversion utility to automate design upgrade. You can also use the mail template conversion utility to convert a mail design from one language to another language. Run the mail conversion utility on an applicable Domino® server.

About this task

Be sure that you have already upgraded the Domino® server that hosts the mail files and the Notes® clients that access those files, or users will not be able to use the features in the new design. Upgrade mail files when users won't be accessing them. Notify users that their mail files will be unavailable during the upgrade.

You can also use the mail conversion utility to migrate from Microsoft™ Exchange.

To use the mail conversion utility

About this task

Before running the mail conversion utility, make sure that all impacted Notes® client installations are upgraded to the new release.

Procedure

  1. Back up any customized mail files or mail templates on the impacted server or client systems.
  2. Start the Domino® server on which you want to run the mail conversion utility and on which the target mail files reside.
  3. Shut down the Domino® server mail router to prevent Domino® from routing mail to the mail files while they are being upgraded. 
    tell router quit

    Mail is stored in MAIL.BOX while you upgrade the mail files. After you upgrade the mail files and load the router task again, the router processes and delivers the mail in MAIL.BOX to the appropriate mail files.

  4. Load the mail conversion utility.
    load convert [arguments]

    The mail conversion utility command uses arguments to specify options of the following form:

    load convert   -? /? -a -c -d -e -f -g -h -i -l -m  -n -o -proxy -r -s -u-w -x mailfilepath existingtemplatename newtemplatefilename

    Mailfilepath specifies which mail file or files to upgrade.

    Existingtemplatename specifies a certain mail file design to upgrade. This property is found in the Template Name field on the Database Properties > Design tab.

    Newtemplatefilename specifies the template with which to upgrade the mail files.

    Table 1. Mail conversion utility options and descriptions

    Options

    Description

    -a Admin Name

    Enables sending mail to the administrator when the convert tool completes.

    -c

    Converts categories to folders.

    -d

    Used to not convert categories to folders.

    -e or -e-

    Enables or disables NSF support for IMAP. Converts the file or files for IMAP use in Notes®.

    -f file name

    Reads the list of databases to process from a text file.

    -gLanguage Name

    Replaces the mail file design with user's preferred language.

    -h

    Adds the IMAP specific items to optimize fetches.

    -i

    Converts categories to folders.

    -l file name

    Generates a list of mail files by reading people's mail files from the Domino® Directory. Writes the list to a text file.

    -m

    Enables or disables folder references which are needed for IMAP. Converts the file or files for IMAP use in Notes®.

    -n

    Shows the databases that match the file name and template name criteria, without actually updating anything.

    -o

    Removes IMAP-specific items.

    -proxy

    Enables a display status and error messages in a console window.

    -r

    Enables recursive search of databases. Converts mail files in subdirectories of the specified directory.

    -s

    Ignores the preserve flag for folders when replacing the design but always preserve them.

    -u

    Enables the upgrade of folders to the same design as the $inbox design.

    -w dir path

    Enables fix up of names in Notes® in all mail files on the server to allow for Microsoft™ Exchange Mail Migration.

    -x

    Enables exclusive design element keys: NAMECLASSLANGUAGE

    -? /?

    Displays help information. Displays command line help.
  5. When the utility is finished upgrading mail files to the current release mail template on the server, start the Domino® server mail router.
    load router
  6. Notify Notes® users that you have upgraded their mail files to the new design.

Mail conversion utility task examples

About this task

You can use the mail conversion utility to convert one or more mail databases to the new design. The following table shows examples of various tasks the mail conversion utility can perform.

Note: When you use a wildcard character, such as an asterisk (*), to specify which files to upgrade to the new mail template, be sure that all databases in the directory (and, if specified, subdirectories) are mail files. When you use a wildcard character, Domino® replaces the design of all databases specified by the wildcard character with the specified template. If you mistakenly replace the design of a non-mail database with the new mail template, use the mail conversion utility to restore the original design and then specify the correct template.
Table 2. Mail conversion utility tasks and descriptions

Task

Description

Upgrade a single mail database

The mail conversion utility replaces the current mail template with the new release mail template.

This example finds the mail database user.nsf in the \MAIL subdirectory of the Notes® data directory. 

load convert mail\user.nsf * mail9.ntf

Upgrade all mail databases in a directory

This example finds all databases in the \MAIL subdirectory of the Notes® data directory that use the Notes® 8.5 mail template, and replaces their design template with mail9.ntf, theHCL Notes® 9.0.1 Social Edition mail template.

load convert mail\*.nsf StdR85Mail mail9.ntf

Upgrade all mail databases in a directory and in its subdirectories

This example finds all databases located in the \MAIL subdirectory of the Notes® data directory and all subdirectories of the \MAIL directory (for example, C:\NOTES\DATA\MAIL\GROUP1, C:\NOTES\DATA\MAIL\GROUP2, and C:\NOTES\DATA\MAIL\GROUP3) and upgrades them to the Notes® 9.0.1 Social Edition mail template, mail9.ntf.

load convert -r mail\*.nsf * mail9.ntf

Upgrade all mail databases listed in a text file

You can create a text file listing databases you want to upgrade and use it with the mail conversion utility to upgrade only those databases. For example, you can create the text file MAILLIST.TXT to list all the mail databases you want to upgrade and save it in the directory C:\TEMP. This example finds all databases listed in MAILLIST.TXT, determines whether the databases use a design template name that matches Mail*, and replaces the designs of the matching databases with mail9.ntf), the Notes® 9.0.1 Social Edition mail template.

load convert -f c:\temp\maillist.txt mail*.ntf mail9.ntf

Create a text file that lists all mail databases in a directory

You can use the mail conversion utility to create a text file that lists all primary mail databases on the server (it does not list replica mail databases). This example creates a text file, MAILLIST.TXT, in the C:\TEMP directory. MAILLIST.TXT contains a list of primary mail databases on the server but excludes replica mail databases. After you create the text file using this option, you can use the file to upgrade the mail databases listed in it. See Upgrading all mail databases listed in a text file in this table.

load convert -l c:\temp\maillist.txt

Convert mail files for use with IMAP in Notes®

If you use a Notes® mail file with IMAP, run the mail conversion utility to enable IMAP-specific features in the mail file. This example readies the mail database user.nsf in the \MAIL subdirectory of the Notes® data directory for use with IMAP.

load convert -e mail\user.nsf

Upgrade custom folder design

You can use the mail conversion utility to upgrade custom folder design to the Inbox design. This example upgrades the custom folder design of all mail databases in the \Mail subdirectory of the Notes® data directory to the Inbox design.

load convert -u mail\*

Upgrade folder design of folders without the Preserve bit

The -s argument ignores any folder or view with preserve deselected. This corresponds to the Do not allow refresh/replace to modify option in the design properties.

System folders and other design elements from the original template used to create the mail file do not have this bit set, even if the database is set to inherit from design. System folders, such as the Inbox, are not updated if you run the mail conversion utility with the -s argument. 

load convert -s mail\*

Convert the English mail template design to a non-English language, for example German

 
load convert -gGerman TestMail.nsf * mail9_en_de.ntf
Note: On the Linux™ platform, do not use quotes around the requested language name. Example syntax for Linux™ is as follows:
load convert -gGerman TestMail.nsf * mail9.ntf

Upgrade all previous users' mail designs listed in maillist.txt to Notes® mail design

 
load convert -u -f maillisttxt * mail9.ntf

Performs address fixup for all Microsoft™ Exchange migrated mail databases in dir_path and its subdirectories

 
load convert -w db_path

Performs address fixup on the given Microsoft™ Exchange migrated mail database.

 
load convert -w mail_db_path

Generates a text list containing all Microsoft™ Exchange migrated mail databases from the primary mail directory, excluding replicas. This feature is of lesser-importance than address fixup but it is necessary in the event that the subsequent option is required.

 
load convert -w -l text_list_path

Performs address fix-up on all Exchange-migrated mail databases listed in the given text list file. Provides flexibility in allowing the administrator to manage the databases that need address fix-up.

 
load convert -w -f text_list_file