Sun Java System Communications Express 6 2005Q1 Administration Guide |
Chapter 7
Migrating PAB Data to Addressbook ServerPreviously Personal Address Book (PAB) was used to store 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 the Addressbook Server instead of PAB to store users’ contact details. Because of this, users accessing Communications Express using existing Messaging Server installations must migrate their PAB data to the Address Book Server.
This chapter contains the following sections:
Overview
The migration tool migrates user’s Messenger Express address book data to the Addressbook 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 addressbook 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 green in Figure 7-2.
Figure 7-2 Location of Entry1 in the PAB tree
After migration, the newly created Addressbook Server Entry is added to the Addressbook Server tree under o=siroe.com, piEntryID=Entry 1 as shown in red in Figure 7-3.
Figure 7-3 Location of Entry 1 in the Addressbook Server tree.
Migration Scenarios
Data Migration takes place in two ways:
Dynamic Migration
Dynamic Migration takes place when an existing Messenger Express user logs into Communication Express. The users receive an email after the migration is completed.
In the dynamic migration process:
- 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.
- Once PAB migration is completed, the Addressbook Server sets the nswmextendedprefs, mepabmigration to "1" in the logged in 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 7-2.
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.
Post Configuration Steps
You need to configure Communications Express to enable migration.
Note
Note that the configuration parameters required for migration must be manually provided by the administrator.
Table 7-1 lists the config files the migration utility depends on.
Table 7-1 Configuration Files and their Purpose
File Name
Description
migrate.properties
Contains the parameters required to migrate data from PAB to Address Book Server. Refer to Table 7-2 for information on these parameters.
uwcauth.properties
Referred by the migration utility to decide whether migration is required.
Migration tool checks for the value of pab_mig_required. If the value is true, dynamic migration takes place
uwcconfig.properties
Administrators can provide the log level and enable logging for trouble shooting purposes. By default this parameter is disabled.
runMigrate.sh
(applicable only for Batch migration)
The script sets the required variables and invokes the java program MigratePab, with following three arguments.
# 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
This file needs to be edited appropriately to provide the necessary paths and arguments.
xlate-pabperson.xml (Table 7-3)
xlate-pabgroup.xml (Table 7-4)
Migration utility internally uses the address Book API’s of Communications Express to load the data from the PAB of the Messenger Express.
The xlate files are required to map LDAP attributes of the PAB to the address Book attributes of the Addressbook Server.
Based on the user's mail host, the PAB configuration entries listed in Table 7-2 are retrieved and the connection to the PAB Server established.
Table 7-3 Field Mapping for Contacts
To receive a mail, you are required to define the parameters mentioned in Table 7-5.
Additional Configuration Required for Horizontal Scalability Support
The attribute psRoot in the User’s LDAP entry is an Addressbook Server compliant URL that defines the LDAP location from which the user’s Personal Address book entries are stored and retrieved. The psRoot attribute enables the administrator provision users so that PAB data for all users is spread across multiple directory locations.
For existing webmail users, if PAB Migration is enabled, the psRoot attribute is constructed using the existing pabURI attribute and a mapping table is defined in uwc-deploy-dir/WEB-INF/config/migrate.properties.
The lookup table in the migrate.properties file consists of the pabhost and pabport entries in the following format:
pabhost.pabport.abhostport = abldaphost:abldapport
where pabhost.pabport refers to the source directory instance and abldaphost and abldaport the target directory instance to which the PAB data is required to be migrated.
Thus, if you want to migrate the pab data from the directory running at pab.example.com:389 to address book directory running at abs.example.com:389 the entry in migrate.properties file should appear as:
pab.example.com.389.abhostport = abs.example.com:389
You may have as many lookups as found necessary in the migrate.properties file. If the pabURI attribute for a user uses pabhost and pabport, the psRoot constructed using the default psRoot pattern will be in the format:
ldap://abldaphost:abldapport/piPStoreOwner=%U,o=%D,o=PiServerDb
If the lookup is not defined for a pabURI value, that is, no entry is provided in the mapping table that matches the pabURI, the pabhost and pabport values are used as the default values for abldaphost and abport. Implying that in the absence of a mapping table, the PAB entries from Messaging Server is migrated to another root in the same directory instance as per the Address Book Schema. In this scenario, the [Target] Directory Instance will be the same as the [Source] Directory Instance.
Migration Deployment 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.