Chapter 7 Migrating Personal Address Book Data to Address Book Server

Previously, Personal Address Book (PAB) was used to store the user’s contacts in Sun Java System Messaging Server and PAB could be accessed only by web-based clients deployed on Messaging Server. The Messaging Server for Communications Express uses Address Book server instead of PAB to store users’ contact details. Because of this, users accessing Communications Express using the existing Messaging Server installations must migrate their PAB data to the Address Book Server.

• Migration Deployment Scenarios

• Migration Scenarios

• Data Migration Process

• Post Configuration Steps

• Additional Configuration Required for Horizontal Scalability Support

Migration Deployment Scenarios

Migration can be performed from:

1. A single Messenger Express instance pointing to the default single PAB host.

2. A single Messenger Express instance pointing to multiple PAB hosts.

3. A single Messenger Express instance pointing to multiple PAB hosts with the default PAB host set.

4. Multiple Messenger Express instances pointing to single PAB host.

5. Multiple Messenger Express instances pointing to multiple PAB hosts.

Migration Scenarios

Data Migration takes place in two ways:

• Dynamic Migration

• Batch Migration

Dynamic Migration

Dynamic Migration takes place when an existing Messenger Express user logs in to Communications Express. The Users receive an email after the migration is completed.

In the dynamic migration process:

1. The application checks if migration has been enabled in the uwcuath.properties file by checking the pab_mig_required parameter.

   If the pab_mig_required parameter is set to true, the migration process is initiated.

2. The login logic then compares the nswmextendedprefs attribute in the user's LDAP entry. It checks for the value of the mepabmigration parameter to determine whether the user’s data has been previously migrated.

3. Once PAB migration is completed, the Address Book Server sets the nswmextendedprefs, mepabmigration properties to 1 in the logged in user entry, to indicate the completion of the migration process.

4. The user receives a mail after the PAB data is successfully migrated to the Address Book Server.

To receive a mail, you are required to set the parameters in the migrate.properties file.

It is recommended that the administrator sends an email to all users informing them that PAB data migration will be triggered during the first login and as a consequence they will not see the Address Book data during the initial sessions. Users should contact the administrator if they are unable to see their data after 2 or 3 days.

Batch Migration

In the batch migration process, migration takes place at the server level without end user interaction. The administrator executes the runMigrate.sh batch script to migrate the mail users PAB data present in a given domain. For mail users present in multiple domains, the administrator will have to invoke the runMigrate.sh script for each domain to migrate users PAB data from the given inetDomainBaseDN to the Address Book Server.

To Perform Batch Migration

Set the following parameters in the runMigrate.sh script. This script is available at uwc-deployed-path/WEB-INF/classes directory.

• BASE_DIR: Set this parameter to the uwc-deployed-path of the Communications Express installation.

• JAVA_HOME: Set this parameter to the directory where Java is installed.

• o=siroe.com, o=isp: Replace the values for siroe.com and isp to the inetDomainBaseDN for your configured domain.

Execute the batch migration script.

# ./runMigrate.sh

If the batch migration fails, exceptions are displayed at the command line prompt.

Migrating a Single User and a Set of Users

Using the migration script, administrators can migrate all the users, a single user, or a set of users. Running the batch migration script without any options migrates the entire set of users. To migrate a single user, you can specify the userid of the user. To migrate a set of users, you should provide the list of users in a text file. The runMigrate.sh command has the following syntax:

./runMigrate.sh{ [-u < [uid] |  [-f <uids-file]} [-h]

where:

• -u option tells the runMigrate script that you want to migrate a single user. The —u option should be followed by the userid of the user who you want to migrate. Here is an example:

  ./runMigrate.sh -u user1

• -f option tells the runMigrate script that you want to migrate a set of users that have been specified in a file. The —f option should be followed by the name of the file that contains the userids of the selected set of users who you want to migrate. Here is an example:

  ./runMigrate.sh -f usersToMigrate.txt

  The usersToMigrate.txt file should contain one userid on a single line. For example:

  user1
  user2
  user3
  ...
  ....
  and so on..

Data Migration Process

Communications Express uses a migration script to migrates user’s Messenger Express address book data to the Address Book Server that is part of Communications Express.

Figure 7–1 Overview of the Data Migration Process

Data residing in the LDAP PAB tree of Messenger Express is migrated to the address book Server LDAP PAB tree. The example below illustrates the migration process.

When User1 in the domain siroe.com has an entry in PAB, such as Entry1 that needs to be migrated, the entry is located in the PAB tree under ou=User1 as shown in Figure 7–2.

Figure 7–2 Location of Entry1 in the PAB tree

After migration, the newly created Address Book Server Entry is added to the Address Book Server tree under o=siroe.com, piEntryID=Entry 1 as shown Figure 7–3.

Figure 7–3 Location of Entry 1 in the Address Book Server tree.

The migration utility migrates all the data from PAB of Messenger Express to Address Book of Communications Express when the user logs in for the first time. However, once data is migrated to Address Book, new contacts or groups created using Messenger Express will not be shown in the Address Book of Communications Express. The reverse is also true.

Post Configuration Steps

You need to configure Communications Express to enable migration.

The configuration parameters required for migration must be manually provided by the administrator.

The following table lists the configuration files that the migration script depends on.

Based on the user's mail host, the PAB configuration entries listed in the table below are retrieved and the connection to the PAB server established.

PAB	Address Book
cn	DisplayName
sn	sn
givenName	givenName
telephonenumber	piPhone1Type:work piPhone1:
homephone	piPhone2Type:home piPhone2;
pager	piPhone4Type:pager piPhone4:
mobile	piPhone3Type:mobile piPhone3:
facsimiletelephonenumber	piPhone5Type:fax piPhone5:
mail	piEmail1Type:work piEmail1:
postoffice+street	homePostalAddress
l	homecity
st	homeState
postalcode	homePostalCode
co	homeCountry
labeleduri	piWebsite1
description	description
memberofpabgroup	memberOfOIGroup
dateOfBirth	dateOfBirth Caution – Due to a limitation in Messenger Express, the migration of this property may be erroneous if you have specified date of birth in a format other than MM/DD/YY. You can however edit this property after the migration and set it to the correct date. Refer to the Online Help for instructions on how to set this.

For more information, see Appendix D, Password Encryption in Communications Express.