2.9 GroupWise Archive Migration Tool

2.9.1 GroupWise Personal Archive Migration Tool

This migration tool is designed to import native GroupWise archives directly into Retain. Also known as the PAM tool.

The GroupWise Archive Migration Tool is found on the tools page. To access the tools page, select the 'tools' link from the top right of the Retain Server administration page.

2.9.2 System Requirements

  • A Windows workstation running GroupWise client 7.0.1 or up. GW 2014 and up use a slightly different file structure so there may be errors.

  • Access to the archives you want to migrate.

  • An HTTP connection to Retain.

2.9.3 Overview; Modes of Operation

There are two modes:

  1. Run at all workstations mode.

    From a command line, you'll run this and it will log into the users mailbox, and then open the local archive. It will then feed messages directly to Retain.

  2. Centralized run.

    This only works if you have all archives stored at a central point.

    In this case, one can conveniently run all of the migrations from a single workstation, and not involve the users at all.

The migration tool uses the GroupWise client to access the archives you want to migrate.

  • In single-user mode, the migration tool will access the mailbox of the logged-in GroupWise user and it will read the archives available to the GroupWise client and send them to the Retain Server you specify.

  • In multi-user mode, it uses the trusted application key to log in to the mailboxes of the users specified in a chosen GroupWise distribution list, attempt to access the archives defined in their mailbox and will send them to the Retain Server you specify.

2.9.4 How it Works

The migration tool does not access the archive files directly. Due to the way GroupWise stores its archives, you need the GroupWise client to read the archives and to hand the data to the migration tool. The migration tool then sends the archives to a Retain Server, much like a worker would.

In normal operation, a Retain Worker reads data from the live GroupWise system and sends it to a Retain Server. With the migration tool, the tool itself is a worker that reads the archived data from the GroupWise client and sends it to a Retain Server.

The migration tool reads the path to the archives as defined in the GroupWise mailbox that you’re accessing. That path must be accessible by the workstation you’re on. It will then ask GroupWise to open the archives and it will read the items in the archive and send them to the Retain Server you have specified.

If you run in single-user mode, the migration tool will access the mailbox currently logged into by the GroupWise client. If none is logged in, GroupWise will be opened and you will be asked to log in.

If you run in multi-user mode, the migration tool will open GroupWise, you can be logged in as any valid user, and it uses the trusted application key to log in to each user specified in a GroupWise distribution list, one at a time.

2.9.5 Prerequisites

The GroupWise client on the workstation you’re using must be able to open the archives you wish to migrate. The process depends on GroupWise being able to access these archives. If you’re migrating the archives of another user, as you would be doing in multi-user mode, you must be able to access that user’s archives from the workstation you’re on.

It is not enough that the archives are on a network-accessible volume. GroupWise must be aware of the path to these archives and that path must be available from the workstation you’re going to use for migration. Refer to the error handling section for important configuration.

2.9.6 Setting It All Up

In multi-user mode, you can use one workstation to migrate the archives of multiple users. In so doing, you can migrate the data without affecting the users in question. In single-user mode, you will run the migration tool on a workstation that has access to the archives you want to migrate (typically the workstation of the user whose archives you’re migrating) and you’ll migrate just one mailbox.

  1. Copy the migration tool files to any directory accessible to your workstation

  2. Log in to the Retain Server you want to migrate the archives to Create a new worker. You’re not actually installing a new Retain Worker anywhere; you’re creating a new bootstrap file for the use of the migration tool so it knows which Retain Server to send the archives to. Be sure the settings listed are accessible and usable by the workstation where you will be running the migration tool. The migration tool uses these settings to log into the Retain Server

  3. Once you’ve saved changes, you will be able to save the bootstrap file. Save it in the directory of the migration tool.

  4. Now start up the migration tool configuration utility. A window will open on top of the configuration utility requiring the location to find the bootstrap file you have just saved.

    (This window will also accept saved configurations from previous sessions.)

2.9.7 Archiving Behavior

  • Date Range – limits or specifies specific mail to process based on a date range.

  • Archive Directory – The location of the archive or archives to be migrated. The default path is assumed unless selected to be specified.

  • Miscellaneous – contains the options to preserve the routing properties in the archive or to add a marker file when the migration is complete.

2.9.8 User Interface

When the Migration Tool is Started - Begin without user intervention the archive process immediately begins without any prompts. Run minimized sets the migration utility to run the migration in the background while the workstation completes other work. The tool may also be set to run automatically on system boot, in case something interrupts the archive job.

When Migration Tool is Running - Contains options to prohibit the user exiting the program before the archive migration is complete and GroupWise login settings. The tool must be able to login and gain access to the archives.

When the Migration Tool has Finished – Contains the behavior of the migration utility on completion; automatic exit, notification, or neither.

CPU priority usage is also set here.







2.9.9 Distribution Lists

In order to process more than one user archive the option must be enabled at the top of this page and the users must be verified against the GroupWise system.

It is recommended to only process multiple archives from the same post office.

The Distribution Lists will only be populated if it is enabled and if the ‘Refresh’ button is selected. It displays the available distribution lists. To have the connection work correctly, the GroupWise Client Parameters on the ‘Connections’ tab must be filled-out with the GroupWise Server IP and port. Displayed lists can be selected. The archives belonging to the users in the selected distribution lists will be migrated. If users from multiple Post Offices are to be migrated, employ some kind of FID clash protection by verifying archives or only processing users which can be verified by a specified Domain and Post Office, (specified in DNS:port or IP address:port).

2.9.10 User List

The User List screen allows the migration of multiple users specified by a user list. The user list is a plain text file with one user ID per line. To enable the process, select the ‘Enable Multiple User Processing Using a Text File checkbox, then browse to and select the desired text file.

2.9.11 Errors

The error limit and actions taken when an error is encountered are specified on this tab.

Errors may be written to the log file, (specified in the next tab), sent in a pop-up message to the user, or sent as an email to the specified address.

The limit of how many errors may be encountered before the migration utility quits the current user is specified. A setting of ‘0’ sets the limit to infinite.

Important: By default, the current user will be skipped after 20 errors by default.

If an email is desired for each error encountered, email settings must be configured. Select ‘Email Options ‘and input the connection information, source address, destination address, and user login information for the SMTP Mail Server.

2.9.12 Logging

The location, logging levels, and buffer of the logging screen are all configured on this tab.

Where Should Log Files be Stored - A specified path, the path to the current location of the application, or a specified path must be selected.

Amount of Detail in the Log Files – The logging level determines how much information is provided in the log files. Unless troubleshooting, log levels of ‘normal’ and ‘errors only’ are sufficient. The buffer size for the logging screen determines how much history the running log screen of the migration tool contains.

2.9.13 Connections

This is an informational page showing the connection settings from the RetainWorker.cfg created in the Retain Server. If this information is incorrect, the Retain Server Connection settings must be modified under the worker configuration in the Retain Server, and a new bootstrap file downloaded for use.

The GroupWise Client Parameters contains the connection information used by the Distribution Lists configuration to allow the Migrator to connect to the GroupWise system.

Provide the POA IP or Hostname, GW Client Port (default: 1677), and the POA SOAP URL. (default: http://<POA>:7191/soap)

Save Configuration

Once the configuration has been setup as desired, click ‘Ok’ and select the location to save the changes into a ‘MigrationTool.cfg’ file.

2.9.14 Running the Migration

The migration tool uses the configuration file to run the job as you have specified in the configuration tool. You may run the configuration tool as often as you need to set up the migration job to your liking.

When run, the tool will prompt for the configuration file, or automatically load the configuration file if the configuration is found it the same directory, and immediately begin the migration. When the tool runs, you will see a screen like this:

You will see any errors in this screen and it will display a notification when the job is complete.

For each user in a multi-user job, it will read the location of the archives from GroupWise and then it will attempt to open the archives. It is critically important that the workstation used for the migration can access the archive files.

2.9.15 Limit of 5 Concurrent Migrations

There is a maximum of 5 migrations permitted at any given time. For instance, if you’re running the migration tool from the workstations of your users, only 5 at a time can be migrated, the others will wait their turn. This is to prevent all the migration requests from overwhelming the server.

2.9.16 Other Notes

The migration tool may be deployed using management tools such as Novell ZENworks. This is one method to collect archives which have been stored on users’ workstations. Users may run the tool manually or it can be run automatically.

UUID errors

[ERROR] Exception: Error getting UUID.

There are a various reasons for a UUID error:

  • The User does not exist in the GroupWise system.

    If the user does not exist in GroupWise anymore but the personal archive needs to be moved into Retain, Retain will create the user mailbox and assign it a Retain UUID (unique user ID). Thus, this is also why the address book needs to be refreshed prior to using the PAM tool. If the user exists in the GroupWise system, you would get two different user mailboxes in Retain if you archived with the PAM tool first and then refreshed the address book in the Retain system.

  • The Users's visibility is set too low in GroupWise.

    In GroupWise, edit the account of the user and set the visibility to System.

  • Apache has been configured to redirect traffic to a secure HTTPS connection.

    Edit the bootstrap file to connect to http://[Retain Server IP address or hostname]:48080 to connect directly to tomcat and bypass the apache redirect.