Sun Java System Communications Express 6 2005Q4 Administration Guide

Chapter 7 Migrating PAB Data to Addressbook Server

Previously 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 Migration

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

PAB tree Structure

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.

Address Book Server tree


Note –

The migration utility migrates all the data from PAB of Messenger Express to Address Book of Communication 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.


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:

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 Post Configuration Steps 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 (Post Configuration Steps)

xlate-pabgroup.xml (Post Configuration Steps)

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\qs mail host, the PAB configuration entries listed in Table 7-2 are retrieved and the connection to the PAB Server established.

Table 7–2 Parameters Configurable for PAB Migration in migrate.properties

Parameter 

Default Value 

Description 

hostname.pabldappoolmin

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

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 

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. 

<pabhost.pabport\>.abhostport=< abldaphost\>:<abldapport\>

 

Specifies the pabhost and pabport entries available in the lookup table in the migrate.properties file.

In this parameter <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.

Table 7–3 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 

homecity 

st 

homeState 

postalcode 

homePostalCode 

co 

homeCountry 

labeleduri 

piWebsite1 

description 

description 

memberofpab 

memberOfPIBook 

memberofpabgroup 

memberOfOIGroup 

Table 7–4 Field Mapping for Groups

PAB 

Address Book 

cn 

displayName 

description 

description 

To receive a mail, you are required to define the parameters mentioned in Table 7-5.

Table 7–5 PAB Migration Email Parameters

Parameters 

Default Value 

Description 

emailReqd 

True 

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


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.


Note –

The lookup table is not defined by the patch installer. You need to define the lookup table after a patch install, and restart the web server.

Ensure that abldaphost:abldapport directory Server instance is defined in the db_config.properties file pointed to by the personalstore.properties of that domain.


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.