Previous      Contents      Index      Next
Sun Java System Communications Express 6 2004Q2 Administration Guide

Chapter 8
Migrating PAB Data to Address Book Server

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

This chapter contains the following sections:

Migration Process
Migration Thread
Migration Scenarios

---

Migration Process

PAB data residing in different directories can be migrated to Address Book Server using the address book migration tool. The migration tool is a standalone executable that migrates user’s Messenger Express address book data to the Address Book Server that is part of Communications Express.

Note	Sun Java System Messenger Express uses a different directory server for maintaining PAB Data from the one used by Address Book in Communications Express. The migration utility migrates all the data from PAB to Address Book 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.

Figure 8-1  Overview of the Data Migration Process

Data migration can take place in two ways:

Batch Migration
Dynamic Migration

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.

Before running the runMigrate.sh script, the administrator should provide the following command line arguments required by the MigratePab utility in runMigrate.sh:

Absolute path of migrate.properties file. The Default path is set to: ../WEB-INF/config/migrate.properties
Absolute path of config directory in which uwcauth.properties and other config files are located. The default path is set to: ../WEBINF/config
inetDomainBaseDN of the users

Dynamic Migration

In the dynamic migration process, data migration is initiated when the user logs into Communications Express for the first time. For dynamic migration to occur, the administrator must enable dynamic migration when configuring Communications Express.

The Migration process depends on:

The type of migration: Dynamic or Batch Migration
Whether the users are registered users of Messenger Express.

Data migration occurs when:

A user logs into Communications Express
A batch process (runMigrate.sh) is executed

Preliminary steps to be performed by the administrator after installing Communications Express are:

Configuring Communications Express to enable dynamic migration.

Note	If dynamic migration is not enabled in uwcauth.properties file, PAB data will not get migrated to the Address Book Server.

Configuring the Address Book Server with the PAB Server details. For example, you need to configure the Host Name, Port Number, BindDN, BindDN Credentials, PAB Host Path and Host Machine names to which the data is to be migrated.

Based on the user's mail host, the PAB configuration entries listed in Table 8-1 are retrieved and the connection to the PAB Server established.

Table 8-1   Field Mapping for Contacts  

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	piEmail2Type:home piEmail1:
mailalternateaddress	piEmail2Type:work piEmail2:
postoffice+street	homePostalAddress
l	homecity
st	homeState
postalcode	homePostalCode
co	homeCountry
labeleduri	piWebsite1
description	description
memberofpab	memberOfPIBook
memberofpabgroup	memberOfOIGroup

Table 8-2  Field Mapping for Groups

PAB	Address Book
cn	displayName
description	description

Dynamic Migration Process

Dynamic Migration occurs when the user logs into Communications Express.

The application checks if migration has been enabled in the uwcuath.properties file and then proceeds with the migration process.
The login logic then compares the nswmextendedprefs attribute with mepabmigration value to determine whether the user’s data has been previously migrated.

If data is being migrated for the first time, the migration thread is started by passing the user ID, domain and userdn of the user.

The PAB migration related configuration parameters are listed in Table 8-4

Table 8-3  Parameters Configurable for PAB Migration in migrate.properties 

Parameter	Default Value	Description
hostname.pabldappoolmin	4	Specifies the minimum number of LDAP user connections to be created for PAB LDAP.
hostname.pabldappoolmax	20	Specifies the maximum number of LDAP user connections to be created for PAB LDAP.
hostname.pabldappooltimeout	50	Specifies the number of seconds before timing out an LDAP connection.
hostname.alwaysusedefaulthost	1	Specifies whether to use the user’s PAB host mentioned in the PAB URI or to use the first fully qualified PAB hostname from the list maintained. When set to 1, the first fully qualified PAB host is used to retrieve the PAB entries.
delete_pabentry	0	Enables the delete of PAB entries and PABURI after a successful migration.
maxthreads	10	Specifies the number of migration threads.
mailhost.pabhosts	The mail host name is assigned to the list of PAB hosts in which the PAB entries are located.	Specifies the list of PAB hosts.
mailhost.pabports		Specifies the port number of the PAB hosts.
mailhost.pabbinddns		Specifies the bind DN for PAB.
mailhost.pabpasswds		Specifies the password of the user binding to the PAB.

Once PAB migration is completed, the Address Book Server sets the nswmextendedprefs, mepabmigration to “1” in the respective user entry to indicate the completion of the migration process.
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 define the parameters mentioned in Table 8-4.

Table 8-4  PAB Migration Email Parameters

Parameters	Default Value	Description
emailReqd	True	Enables a mail to be sent after the PAB data has been migrated successfully. Accepted values are “True” and “False”.
smtphost	local mail host For example: budgie.siroe.com	Specifies the SMTP relay host name.
smtpport	25	Specifies the SMTP relay port.
mailsubject	PAB Migration Status	Specifies the subject of the mail.
from	admin@hostname	Specifies the sender’s name.

Tip	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.

---

Migration Thread

During migration, the migration thread confirms whether the user is a mail user and then finds the PAB details from uwcconfig.properties file for the mail user. The uwcconfig.properties file contains the default PAB host name or multiple PAB host names (if the user is present on multiple domains). Based on these entries, Address Book determines the appropriate PAB host to which the data should be migrated and establishes the connection.

Example

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 green in Figure 8-2.

Figure 8-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, cn=Entry 1 as shown in red in Figure 8-3.

Figure 8-3  Location of Entry 1 in the Address Book Server tree.

A new configuration file is added in the Address Book Server called migrate.properties that has the following details:

Server name, port number, basedn, binddn, binddn password of PAB Directory Servers. There may be one or more directory servers where PAB can be stored. If there are many directory servers, one of them must be made the default server.
Server name, port number, basedn, binddn, binddn password of directory server where Address Book Server’s personal store data is stored.

To migrate data the migration tool needs to know whether:

PABURI attribute must be used for deciding the directory server where each user's PAB is stored, or
The default directory server should be considered from the list of directory servers.

---

Migration Scenarios

Migration can be performed from:

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

Previous      Contents      Index      Next

---

Copyright 2004 Sun Microsystems, Inc. All rights reserved.