PAM: Instructions for the GroupWise Personal Archive Migration Tool

PAM: Instructions for the GroupWise Personal Archive Migration Tool

The PAM (personal archive migration) tool is a separate utility designed to migrate GroupWise personal archives to the centralized Retain archive system. To run this program please note the following conditions and steps below:


REQUIREMENTS / PREPARATION

The PAM tool only runs on Windows Operating Systems. The following Windows versions with latest service packs are supported with PAM:

• • Windows 2003 Server
  • Windows 2008 Server
  • Windows XP Professional
  • Windows 7
  • Windows 8

PAM can run both on 32 and 64 bit systems.

GroupWise client

The GroupWise client is required to be installed on the the workstation running the PAM tool because it utilizes the GroupWise API.  These are the supported client versions and their associated Support Packs:

• • GroupWise 8
  • GroupWise 2012
  • GroupWise 2014

Retain Installation

The main Retain software must be installed and the system configured prior to running the PAM tool:

• • A valid Retain license must be uploaded to the Retain Server.
  • The GroupWise module must be configured.
  • The address book must be refreshed in order to cache the address book from the GroupWise system.

Note: The user does not necessarily have to exist in the GroupWise system to be able to be archived.  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.

Location of GroupWise Personal Archives

Single User

It is important to know  the location of the personal archives.  If the archive path stored in the GroupWise client options (Tools | Options | Environment | File Location | Archive Directory) is accurate and is accessible from the workstation from which you are running PAM, it will use that path in the client options if configured to do so. 

If the personal archive directory has moved to a different location than what is specified in the user's client options, you can configure the PAM tool to look at that new path.

Multiple Users

If you are wanting to archive multiple users, a centralized network location can be used to store each of the users' personal GroupWise archive directories. A NOTE OF CAUTION: User FIDs are not necessarily unique across post offices.  Since the GroupWise personal archive directories are uniquely named using the user's FID (of[FID]arc), you could inadvertently overwrite one user's archive directory with another user who has the same FID.  Thus, before copying all of the personal archive directories to a centralized network path, make sure all the FIDs are unique.  If they are not, you may want to create a directory named after the GroupWise userid for each user and copy their archive directory into that directory.  PAM is designed to handle such configurations as will be explained later in this article.

GWCHECK:  

It is highly recommended to run a GWCHECK maintenance (full, content, analyze, fix) on the personal archives before running the PAM tool. The reason for this is to correct any problems with messages, databases, etc.  This can save a lot of time when running the tool by preventing errors. GWCHECK is also an efficient troubleshooting step to fix any data related errors that occur after running the PAM tool.

To run a GWHECK on the archives, please see the following link: Run GWCHECK on Archives

INITIAL MIGRATION CONFIGURATION INSTRUCTIONS

1.  Create or generate a Worker boostrap (RetainWorker2.cfg) from your Retain system.

PAM reads the Worker bootstrap file to get the GroupWise trusted application key (TAK) as well as the IP address or DNS hostname to the Retain Server so it can later connect to it to send the archive files over to the Server.  None of the other configuration options in the Worker object affect the PAM tool, so do not worry about those.

Before downloading the Worker bootstrap, just make sure that under its "Connection" tab, the "Server Host Name" gives a valid IP address or DNS hostname that will work from the workstation from which the PAM tool will be attempting.  If this is all accurate, you can simply go to the Bootstrap tab of your Worker object in the Retain web admin tool and click on the link to download the bootstrap.  Or, if you know where a previously downloaded bootstrap is stored, you can use that as long as it has accurate information.

Remember, the PAM only needs the bootstrap in order to get the GroupWise trusted application key (TAK) necessary to access user mailboxes and the IP address / DNS hostname of the Retain Server.  If your TAK or the Server's host name has changed since your Worker was configured, the PAM tool will not work.

Another option is you can create a new "Worker" for the PAM tool.  That Worker object would not be used by Retain, but taking this step allows you to download a bootstrap.  Once that boostrap has been downloaded, you could simply delete the new Worker object you created if you desire to do so.

To create a new Worker object, see "How to Create a Retain Worker".

2.  Run the Migration Configuration Tool to configure the options for the migration tool.

• Download the latest version of the tool:  http://download.gwava.com/download.php?product=RetainPAMTool&version=versions
• Click on MigrationToolConfigurationUtility.exe
• As it loads, it prompts you to upload the the RetainWorker2.cfg (bootstrap) file into PAM.  Browse to the location of the bootstrap you previously downloaded in step #1 and click Ok. 

This will load the connection settings to the Retain Server into the PAM configuration file.

• Click on the Connections tab.  Here you'll see that it brought in the Retain Server URL and the GroupWise Trusted Application Key (TAK).  However, it defaults the name of the key to "Retain".  This may not be what you named your TAK in GroupWise.  You can check this in GroupWise or you can go to the GroupWise Module configuration page in the Retain Server admin tool (Configuration | Module Configuration | GroupWise | SOAP).  Use the same "Trusted Key Name" as is specified on that screen.

MIGRATION CONFIGURATION OPTIONS EXPLAINED

The migration tool configuration utility has seven tabs. We will explain the options under each tab and in the next section we will take you through various types of jobs.
Archiving Behavior (TAB)Date range of items to archive

"Process all messages in archive, regardless of date."

1. • Select this option if you want to process all messages in the database with no date filter.

• "Process items within a specified date range."

1. • Select this option if you want to only process messages that fall in a specified date range and not all the messages.
     

Determining where the archive directory is located

• "Let GroupWise automatically try to open the archive. This assumes the archive location set in GroupWise client options is accessible."

1. • If you go into the GroupWise client (Options) there is a path specified that you archive to. If this path is set, then the configuration tool will look to that path in order to locate the archive and open it. Selecting this option will not work if that path is not set or there is not an archive file at that path location.

• "Use the path specified below as the base path. All archive directories will be assumed to be direct subdirectories of this path."

1. • If you select this option, you will need to specify a path to the archive file you are wanting to migrate. You would not put the file name in, just the path to the folder where the file is located.
   
   

Miscellaneous

• "Include routing properties?"
  •  Selecting this will keep the internet routing headers from the original archive message in GroupWise and  import it into the retain archive. This is a preference item.
• "Create marker file when an archive is complete"
  • Selecting this will create a file in working directory.

User Interface (TAB)

1. When the migration tool is started
   • Begin archiving without user intervention
     • If selected, this will do exactly as it specifies, it will run without any user intervention. If it is not checked, the program will start but then stop and wait for the user to find the app in the systray, right click on it, and hit start before the program will run on the archive.
   • Run the tool minimized in the system tray
     • If selected, the migration tool will run hidden in the system tray (run in the background)
   • Add the tool to the startup menu of Windows, so if it is interrupted, it will run again on reboot
     • If selected, this will create a shortcut in startup so that the migration tool will run on startup if it is interrupted while running by a power outage or accidental shutdown.
2. While the migration tool is running

   • Do not permit the user to exit the tool before it is finished

     • If selected, this will keep the user, whose desktop the migration tool is running on, from being able to exit the program.

   • Prompt for GroupWise login
     • If selected, this will prompt for a user login for GroupWise in order to start migrating.

   • Use current GroupWise login or wait silently for valid login

     • If selected, this will use the credentials of the person already logged into GroupWise on the machine if it is open.
3. When the migration tool has finished
   • Exit the tool automatically

     • If selected, this will cause the migration tool to exit automatically when finished running.
   • Let the user know the migration is complete with a popup
     • When the migration tool finishes, a popup will let the user know it is finished.

Distribution Lists (TAB)

• • Enable multiple user processing using GW distribution lists
    • If selected, you are able to select from the list of distribution lists to migrate from GroupWise.

• • Verify Current User Matches GW Archive
    • If selected this will verify that the current user FID matches the GroupWise archive FID

• • Only process users in the list where the domain is........and the post office is.........
    • If selected it will only process users within the selected distribution group that meets the criteria of being in the domain and post office specified.

User List (TAB)

• • Enable Multiple User Processing Using a Text File
    • If selected, you are able to select a predifined list (.txt file) of users to process.

• • Append UserID to Archive Location
    • If selected, this will add the userID to the path of the archive file (i.e. C:\Users\root\Desktop\GWArchives\UserID\OFxxxAR)

• • Append Sub-Directories to UserID
    • If selected, this will add user defined Sub-directories to the path of the archive file (i.e. C:\Users\root\Desktop\GWArchives\UserID\[USER DEFINED]\OFxxxAR)

Errors (TAB)

1. When an error occurs during archiving
   • Write the error to the log file
     • If selected, this will Write any error that it encounters to the log file.
   • Alert the user with a popup message
     • If Selected, the user will be notified of the error with a popup window.
   • Send an e-mail message
     • If Selected, the user will receive an email upon encountering an error (Specify email address)
   • Stop archiving the current user after [xx] errors occur
     • This will cause the process to quit running after it encounters the user specified number of errors.

1. Where should the log files be stored
   • Application Data\RetainMigrationTool
     • If selected, the log files will be stored in Application folder "\Application Data\RetainMigrationTool\"
   • Application Path
     • If Selected, the log files will be stored in the application folder.
   • Selected Folder:
     • If Selected, the log files will be stored in the path the user specifies.
2. Amount of detail in the log files

   • Log Level

     • You have four options..."Errors only" will give you the least information in the log if there is an error. "Basic Information" will give you more but still not much. "Verbose" even more information on errors. "Diagnostic" will give you the most.
     • The more information you have when there are errors the better, but they also make for bigger logs files that take up space. You can run "Errors only" when you are not having problems and if you start to have problems, switch it over to diagnostic in order to have the most information if you start to get errors.

   • Screen Buffer Size
     • This determines how large the scrollable screen display is, the more lines that are buffered, the more memory it takes.

   • Display URL's in Log

     • If selected it will display the URL's in the log files

Connections (TAB)

1. Retain Server Connection
   • URL to connect to Retain Serve:
     • This displays the URL that the migration tool will connect to in order to do the migration.
   • Name:
     • This disoplays the name of the worker that is being connected to in your Retain Server.
2. GroupWise Client Parameters

   • GroupWise Server IP

     • This is where you will enter the IP Address of the GroupWise Post Office Server.

   • GroupWiser Server Port
     • This is where you will enter the Server port (default 1677).
3. GroupWise Trusted App
   • Name:

     • You will put the same name here that you used for the Groupwise Trusted App Key in Retain.

     
      

ARCHIVING A SINGLE MAILBOX

• If running the PAM tool against a single mailbox, it might be easier if you run the tool on the same workstation that contains the local archives for the user; otherwise, you can copy their archives to a network location but you will need their GroupWise credentials in order to run the PAM tool.  If you cannot get those credentials, then you are best off running it on the user's workstation while the user is logged into GroupWise (the GroupWise client can be minimized).

• Start first at the Archiving Behavior TAB above. 
  

• 1.  Select the option: "Let GroupWise automatically try to open the archive." 

• This assumes the archive location set Tools | Options | Environment | File Location in the user's mailbox is accessible.

• If not, then specify the path using the option below it ("Use the path specified below...").

  Once that is complete, confirm all of the other configuration settings in User Interface, Errors, and Logging. Then click Ok.
  

  • Save the migrationtool.cfg to the application directory.

ARCHIVING MULTIPLE MAILBOXES

• The PAM tool has the ability to run against multiple archives, and send them to the Retain Server. To do this it is important that all of the archives are stored in a network location that can be accessed by the Windows box (mapped drive is recommended).

• To configure the PAM tool to run multiple mailboxes launch MigrationToolConfigurationUtility.exe  and upload the bootstrap file. 

• In the Archiving Behavior TAB,  select the option..."Use the path specified below as the base path". All archive directories will be assumed to be direct subdirectories of this path:   Enter in the path to the location where the personal archives are located.

There are 2 ways to run the tool for multiple archives.

1) Multiple Archive Processing/Distribution Lists
The first way to run multiple user archives with the PAM tool is through the Distribution Lists

Click on Distribution Lists TAB.
Enter in the POA and port that contains the Distribution Lists.
Click on the Refresh Button. The Distribution lists should appear. If not, check the GroupWise Server IP and port and try again.
Select the lists you wish to have archived. 

2) Multiple Archive Processing/User List
The 2nd way of running multiple archive processing is through the User list. Click on the User List tab. 

It is important that a centralized location of the archives is created prior to running the archive job.  Please verify the list of users contain an archive in the file location specified in Archiving Behavior tab.

· Click on Enable Multiple User Processing Using a Text File to enable this feature.

There are two ways to enter in a list of users that are to be archived.

1)      Select List of Users to Process. This option will upload a text file with a list of users that are to be archived. The text file must be created manually, and each mailbox id inserted on their own line. Once the text file is uploaded, the users will show in the Users to Process box.

2) Users to Process. This box will show the list of users that will be archived during the job. If a text file is uploaded, the list of users will show. The names can be edited, and names can be typed in. Be sure that each user is on their own line.

Once the configuration is complete, click on Ok. Save the MigrationTool.cfg to the application directory of the PAM tool.

Note: The other settings, in user interface, errors and logging can be changed for convenience. The settings can be let at defaults. For troubleshooting purposes, please set the logging level to diagnostic. 

Run the MigrationTool.exe to begin the archiving process.

This article was originally published in the GWAVA knowledgebase as article ID 2194