In-Depth

Keep Your Migration From Heading South

If you’re planning on migrating users from GroupWise to Exchange, consider the Exchange Migration Wizard as a free alternative to expensive third-party options.

• By Mark England
• 01/01/2003

YOU’VE DECIDED TO take the big plunge and move your company from Novell GroupWise to Microsoft Exchange 2000. One of the primary tasks—if not the most important—of a GroupWise to Exchange migration is the job of migrating mail and calendars. Some of the other challenges are maintaining coexistence, removing the GroupWise client and installing Outlook or another MAPI e-mail client; not to mention designing, installing and configuring a new messaging system such as Exchange. Each of these tasks can be a major project in itself.

The focus on this article is the Exchange Server Migration Wizard, installed as part of Exchange. I assume you’ve already installed Exchange.

For administrators, it’s important to thoroughly understand the process of migrating users’ messaging data and to know that when you enter a coexistence state, your e-mail infrastructure will become more complex. Information and expectation management are the keys to success.

The Migration Server
While you can run the migration utility from any workstation or server that’s a member of the same forest as the Exchange servers, I recommend creating a dedicated migration server. The migration server can be either a server or a high-end workstation physically located as close to both the GroupWise and Exchange servers as possible (the same network segment is preferred). I’ve found that running Windows 2000 Server versus Win2K Pro on the server provided better performance. The migration server shouldn’t be used for other purposes; at times it can be “touchy,” with the mix of network and client access software required on it (see Table 1) and may need to be rebooted from time to time during extended migration projects. By dedicating the migration server to migrations only, I’ve had great success. You can also have as many migration servers as you need. Depending on the configuration of the migration server, one subsystem may be affected more than others. For one project on which I recently worked, the client chose a piece of hardware with a very slow IDE disk drive, causing extremely slow migrations due to delayed disk drive performance.

Table 1. Migration Server Configuration

Item Comments Windows 2000 server – latest service pack This can be Server or Advanced Server. Member of Exchange forest Exchange System Manager – latest service pack ESM provides the communication with Exchange and the ability to manage user and contact objects. Novell Client version 4.8 Needed to talk with Novell and GroupWise. GroupWise Client 5.2.0 Needed to access GroupWise. NWCLIENT installed Even if the Netware server hosting GroupWise is running TCP/IP, IPX/SPX is needed in order to talk with the GroupWise server.

The GroupWise client version is the most critical piece of the migration server. The Wizard uses the GroupWise client API to access mailboxes on GroupWise Server. Because the API changes with almost every version of the GroupWise client and the Wizard isn’t revised with every version of GroupWise released by Novell, using version 5.2.0 will give the most reliable results. This is an exception to the rule of having the most current version running. I’ve also had good success with version 5.2.5.

Figure 1 shows an overview of where the migration server logically sits in the big picture. The migration server connects to both the GroupWise and Exchange worlds. In this example, the migration server points to a bridgehead server on the Exchange side and on the GroupWise side points to a Novell server running the API Gateway and hosting the primary domain.

Figure 1. The migration server sits between the GroupWise and Exchange environments (logical overview).

Note that the migration server needs to be connected to the GroupWise Primary Domain database—allowing it to find the API gateway link via the Message Transfer Agent (MTA) connectors. For ease of migration, it’s suggested that the API gateway be installed to and connected via the primary domain MTA. If the user you’re migrating is hosted in a secondary domain, you need to be authenticated to the server hosting this domain. The primary concern is that the migration server is connected to the same post office on which the user being migrated resides. This would still hold true if domains and post offices exist in different trees.

Tip: Installing the Novell GroupWise Connector isn’t necessary to migrate users from GroupWise to Exchange. While I haven’t seen a migration done without using the Connector, it can technically be done with no problem.

Figure 2 shows an example of the error received when the migration server is unable to talk to the GroupWise server. At first glance you might assume this is an access issue or lack of proxy rights on the GroupWise side; but the problem in this case is the wrong version of the GroupWise client on the migration server. This error was caused by using a version newer than 5.2.0. Installing version 5.2.0 fixed the problem.

Figure 2. The migration has ended because of errors. In this case, the errors were caused by the incorrect GroupWise client version being installed on migration server.

The Migration Wizard
The Migration Wizard is used to extract user data—mail and calendars—from GroupWise. It can’t migrate GroupWise archives, personal address books or frequent contacts.

Tip: UniAccess, by ComAxis, http://comaxis.com, is a handy utility that allows the migration of GroupWise data, including archives, frequent contacts and personal address books. UniAccess is fully scriptable and easy to use by administrators and/or users.

The Wizard gives you the option to perform your migration in either a one- or two-step process. If you choose to migrate using the one-step method, data is extracted and imported into Exchange by running the Wizard one time. If you choose to migrate using the two-step process, you’ll need to run the Wizard twice. The first time all data will be written to the location specified in the Wizard (normally the local drive). You then run the Wizard a second time to import the mail from the temporary location into Exchange. The two-step process is often used when the one-step process fails. The one-step process sometimes fails with large mailboxes; in my experience, with GroupWise mailboxes over 300MB or 400MB, the two-step process seems to work better. The two-step process may also be needed if the GroupWise server isn’t in perfect health and the Wizard has a hard time holding a connection to it.

Migration Wizard Internals
Whichever process you choose, the following process occurs when data is extracted from GroupWise and written to the local drive. As mentioned above, the Wizard extracts from GroupWise and writes the data to a temporary directory. The Wizard uses Intermediate File Format (IFF) files in all types of migrations it performs. IFF files are comma-separated-value (CSV) files and can be viewed by Notepad or any text editor. Data is written to IFF files as it’s extracted from GroupWise. If you’re extracting a large post office (or single user) that contains gigabytes of data, your IFF files will also be gigabytes in size. There are three types of IFF files, identified by their file extensions:

• Packing List (.pkl): The .pkl file is a list or inventory of all other IFF files relating to that migration session. The Wizard uses this list as a reference for all the IFF files involved in the migration session. When you perform the second step of a two-step migration, the Wizard uses the .pkl file to get started.
• Primary (.pri): There’s one .pri file for each user, and one .pri file for the directory information of all users, so if you’re migrating five users, six .pri files are created. The Directory.pri file contains a list of the exported users and their properties (display name, alias, addressing and so on). The other .pri files contain the user’s mail messages, whic are named in numbered sequence: 00000001. pri, 00000002. pri and so on.
• Secondary (.sec): The .sec files are used to hold large amounts of data, such as the body of a message or message attachments. The .pri files contain pointers to data in the .sec file. In other words, a user’s .pri file contains message properties such as To, From, Cc, Subject, Date, Time and so on. It also has a pointer that says to look in a specific .sec file beginning at a specific byte to get the body for this message. Any data amount in a message that exceeds 256 bytes is put in the .sec file, and a pointer to this data takes its place in the .pri file (some parts of messages, such as the body, are always put in the .sec file, even if they’re shorter than 256 bytes).

After a user’s been successfully migrated, as shown in Figure 3, the temporary directory can be deleted. This isn’t done automatically, so care must be taken not to run out of disk space.

Figure 3. The Wizard has imported four out of 38 messages. When complete, the Wizard should show zero errors.

The Migration Account
To use the migration utility, you’ll need an account that has access to Exchange, GroupWise, NetWare and the users’ mailboxes on both messaging systems. The best practice is to create an account in both environments that has the same username and password. An example would be to create an account called “GW2EX” (GroupWise to Exchange). On the Windows side, the account will need Exchange Admin rights or Domain Admin rights (or admin rights to the Organizational Unit that holds both the GroupWise contacts and the new Mailbox-enabled object). While you don’t have to provide full rights in NetWare and GroupWise, if you don’t, you’ll spend weeks granting all the specific access required—object by object. It’s obviously easier to just grant full rights to the system as well, right from the start.

Running the Wizard
Now that the prep work’s completed and Exchange is ready to receive GroupWise users, it’s time to run the Wizard. Table 2 provides a checklist of tasks that must be completed prior to running the Wizard. Here’s a quick explanation of each item in Table 2.

Table 2. Pre-Migration Checklist

Item Task 1 Import GroupWise archives that the user would like converted and migrated to Exchange. 2 Set or clear the password on a GroupWise mailbox. 3 Set the visibility of a GroupWise mailbox to “system.” 4 Give the migration account proxy rights for the GroupWise mailbox. The migration account should be the only account with proxy access. 5 Send a personalized mail to the new Exchange mailbox.

• Item 1: As mentioned before, the Migration Wizard won’t migrate GroupWise archives; thus one option is for the user to import his or her GroupWise archives back into his or her mailbox so the Wizard will convert them to Exchange during the migration. This might not be possible, though, for power users with gigabytes of GroupWise archives and limited disk space on the existing GroupWise server.
• Item 2: When running the Wizard, you’ll need to provide the password for the user’s mailbox.
• Item 3: The visibility of the GroupWise mailbox must be set to “system” or the migration utility won’t see the mailbox when it scans the GroupWise server.
• Item 4: The account running the Wizard will need Read access to the users’ mailboxes. A best practice is to delete all other proxy access, as the Wizard sometimes gets confused when reading proxy access.
• Item 5: Although not mandatory, a welcome message to users explaining how to access old calendars and welcoming them to the new messaging environment is helpful.

Tip: A utility called GroupWise Bulk (GWBulk), written by Microsoft Consulting Services, is available to help automate many of the cumbersome Table 2 tasks. This tool, provided “as is,” isn’t formally supported by Microsoft; however, the source code is available should you wish to make any modifications or add functionality yourself. While GWBulk is functional and can save a large amount of time during preparation and migration, it should be tested in your specific environment.

Running the Wizard is a very straightforward process. However, there are a few catches:

• If you receive a “duplicate error” after selecting the account you’re migrating, find the mail-enabled contact created by the Novell GroupWise Connector and delete it. Depending on which domain controller you’re authenticating to, you may need to wait for replication to catch up before running the Wizard again.
• Having accounts other than the migration account with proxy access to the existing GroupWise account will cause a failure.
• After the Wizard finishes running, use Outlook or OWA to check that mail has migrated successfully. If so, delete the user from GroupWise. If you don’t delete the user and only change the “visibility” to “hidden” in GroupWise, existing GroupWise users will still be able to send mail to the user by using the user’s alias name, which will resolve via LDAP in GroupWise even though the user’s hidden. The newly created Exchange user will be replicated to GroupWise and added to the GroupWise Address Book. This should happen within a few minutes.

Note: If you choose not to delete the GroupWise user for any reason, you may end up with a reply problem, as you’ll lose the legacyExchangeDN from the contact object.

Calendar Migration
The Wizard will migrate users’ calendars, but it isn’t fun for users to export the calendar entries back into Exchange. The Wizard pulls all the calendar entries from GroupWise, inserts them into a Schedule+ file, then attach it to an e-mail for the user. This e-mail will normally be the first one in the user’s inbox, which makes it easy for the user to find. After the migration, the user must save the file and then use the Import utility to import the file into Outlook. In Outlook XP, the message is the first one in the inbox; when the user runs Outlook for the first time it will prompt the user and ask if he or she wants it to import the file automatically.

This is a complicated process for the user; however, I’ve seen hundreds of calendar appointments come across and get imported into Outlook just fine. Another positive aspect is the fact that this all happens as part of running the Wizard. The downside to this process is that successfully completing the task of importing calendars falls squarely on the shoulders of the users. I haven’t found any helpful shortcuts for the user other than using a third-party utility as mentioned earlier.

Problems to Avoid, Lessons Learned
Use the same password for all accounts. It makes using the Wizard much easier.

The migration account must be in the same GroupWise post office as the accounts you plan to migrate. Simply create a migration account for each post office (and try to migrate one post office at a time so you can use the same account).

To migrate accounts, the Wizard must point to the GroupWise domain that contains the post offices with the users who need to migrate. If the Wizard can’t communicate with the post offices in secondary GroupWise domains—even if the Wizard points to the primary GroupWise domain—users from these post offices can’t be migrated.

The Wizard’s much faster when the GroupWise server is in direct-access mode rather than client/server mode. Direct-access mode requires configuration on both the client and server sides.

If the GroupWise user has a nickname, remove it. The Wizard incorrectly grabs the nickname field instead of the user’s alias.

You may encounter a situation in which some accounts are still unable to migrate, even though the migration account was granted Minimum User Access rights on every GroupWise account. If that occurs, explicitly grant the migration account all proxy rights to the user’s account.

Free Is Good
The Wizard has some limitations; still, it’s provided free with Exchange and may provide enough functionality for most projects. With the current economic environment, where saving every dime counts, you may not be able to afford third-party migration products. In that case, the Migration Wizard looks even better. But remember, as with any project, the key to success is lab testing and developing a good project plan.