This chapter describes how to migrate information from Oracle Communications Convergence Personal Address Book (PAB) to Oracle Communications Contacts Server.
Contacts Server stores users' contact information in either a MySQL Server or Oracle database. Convergence stores Personal Address Book (PAB) data in LDAP in Directory Server. To use PAB contact data in Contacts Server, you must migrate it by using the davadmin migration command.
The davadmin migration command migrates Convergence PAB contacts and contact groups to the Contacts Server back-end database in vCard format. The migration transfers whatever information is found in the LDAP directory to the Contacts Server back-end database. Additionally, if you migrate the same PAB address book multiple times, the user does not end up with duplicate data in the migrated address book.
Note:
Original PAB LDAP entries remain the same after migration. Keep these entries in the short term while diagnosing any migration issues.The data migration process assumes the following conditions:
You can take a reasonable amount of downtime to complete the migration.
You can perform a trial run to check results before doing the actual migration.
You can examine and fix address books that failed to migrate, by examining the master_log and user_log files for errors, then rerunning the migration on those address books that failed.
If your deployment consists of multiple domains, you have configured ACIs to allow the Contacts Server administrator ID search and read access to non-default domains.
Note:
You can also have a coexistent deployment of Contacts Server and PAB hosts. For more information, see the topic on address book co-existence in Contacts Server Installation and Configuration Guide.The Convergence PAB stores users' contact information in the Directory Server LDAP directory under the distinguished name o=PiServerDb. The following example shows the directory structure in which the address book entries for user jsmith are located:
o=PiServerDb
o=example.com
o=piPStoreOwner=jsmith
The following sample LDIF file shows the LDAP entries that store address book data for the user jsmith under the o=piPStoreOwner entry. The example includes entries for the user's personal address book, corporate directory, and personal store:
dn: piPStoreOwner=jsmith,o=example.com,o=PiServerDb piDefaultAB: e10976f864e00 lastPurgeDate: 20060217T074523Z piPStoreOwner: jsmith objectClass: piPStoreRoot objectClass: top dn: piEntryID=e10976f864e00,piPStoreOwner=jsmith,o=example.com, o=PiServerDb displayName: Personal Address Book objectClass: PITYPEBOOK objectClass: piLocalBook objectClass: top piEntryID: e10976f864e00 multiLineDescription: This is your Business Address Book piBookType: abook dn: piEntryID=e10976f865771,piPStoreOwner=jsmith,o=example.com, o=PiServerDb displayName: Corporate Directory objectClass: PITYPEBOOK objectClass: piRemoteBook objectClass: top piEntryID: e10976f865771 multiLineDescription: This is your Corporate Directory piRemotePiURL: ldap://corpdirectory piBookType: abook dn: piEntryID=e10976f8659f2,piPStoreOwner=jsmith,o=example.com, o=PiServerDb displayName: Applications objectClass: PITYPEBOOK objectClass: top piEntryID: e10976f8659f2 piBookType: pbook dn: piEntryID=e10976f865bd3,piPStoreOwner=jsmith,o=example.com, o=PiServerDb displayName: Personal Store objectClass: PITYPEPROFILE objectClass: piEntry objectClass: top piEntryID: e10976f865bd3 memberOfPIBook: e10976f8659f2 dn: piEntryID=e10976f8665f4,piPStoreOwner=jsmith,o=example.com, o=PiServerDb displayName: Applications objectClass: PITYPEPROFILE objectClass: piEntry objectClass: top piEntryID: e10976f8665f4 memberOfPIBook: e10976f8659f2
Each PAB address book becomes a corresponding address book in the Contacts Server back-end database for the user, except for the Corporate Directory and Certificate Book. The migration does not migrate those entities. The migration uses the PAB address book's piEntryID as the URI of the address book, except for the default address book. Because a Contacts Server account is created with a default URI of addressbook, the migrated default PAB address book uses its piEntryID as the URI.
The migration process involves the following high-level steps:
The davadmin migration command locates the user's PAB address book and retrieves its LDAP entry.
To determine the search base for the user and address books under the o=PiServerDb tree, the migration process uses either the psRoot attribute, or, if it is empty, constructs a lookup of the user's uid and email domain.
The migration process performs an LDAP search on the base piPStoreOwner=uid, o=domain, o=PiServerDb using the filter (&(objectclass=PITYPEBOOK)(piBookType=abook)) to return the list of address books for the user.
The migration process makes each address book into a corresponding collection in the Contacts Server back-end database for the user, except for the Corporate Directory and Certificate Book, which are not migrated.
To get the list of contacts for each address book, the migration process performs an LDAP search on the base piPStoreOwner=uid, o=domain, o=PiServerDb using the filter (&(objectclass=PITYPEPERSON)(objectclass=piEntry)(memberOfPIBook="bookentryid")) where bookentryid is the piEntryID of the address book.
The migration process transforms the LDAP entry of the contact into vCard format for storing in the Contacts Server back-end database. This transformation uses an LDIF-to-vCard import mechanism translation file. This translation file defines the mapping of various PAB LDAP attributes to their vCard counterparts.
Each transformed contact becomes a node under the address book collection using the URI formed by the piEntryID, which is appended with a .vcf file extension.
To migrate PAB information to Contacts Server, run the davadmin migration migrate command. For more information, see "Contacts Server Command-Line Utilities".
Note:
You must use the davadmin migration command to migrate contacts from the Convergence PAB to Contacts Server. Do not export and import contacts as CSV files as a way of migrating the contacts.For example, to migrate the address books and contacts for a single user john.smith@example.com:
davadmin migration migrate -a john.smith@example.com -X "cn=Directory Manager" -L pab-ds.example.com:636 -l /tmp -S
Enter Admin password:
Enter Migration Admin password:
log tag = /tmp/nabserver_migration/2012-11-05_113142/master_log
Each migration creates a migration log file (master_log), which logs the list of users migrated, along with a success or failure status. This log file name is returned as the log tag value when the davadmin migration command completes. You can use this log tag to display the migration status by running the davadmin migration status command.Each migration also creates a separate migration log per user (user_log) located in a subdirectory named with the user's email address. This log shows each address book processed and the contact entries of the migrated address book.
For example, to check on the status of the migration:
davadmin migration status -G /tmp/nabserver_migration/2012-11-05_113142/master_log
Enter Admin password:
[john.smith@example.com] Migration begin
[john.smith@example.com] Migration completed
Troubleshooting the migration involves looking at the following errors:
If your migration produces errors similar to the following:
[user@host.example.com] Validation exception: backend throws an error (com.sun.comms.nabserver.backends.BackendException: SQL error: Error in allocating a connection. Cause: In-use connections equal max-pool-size and expired max-wait-time. Cannot allocate more connections.(INTERNAL_STORE_ERROR)) while doing nodeExists on dav/home/user@host.example.com/addressbook/dropbox/00000000000 000000000000000000000405ce44e000063da0000003100004aa0/ while storing: 00000000000000000000000000000000405ce44e000063da0000003100004aa0
then you might need to do the following:
Reduce the value of davcore.serverlimits.maxmigrationthreads.
The default value is 2. Try changing the value to 2*(number of CPUs).
Change the MySQL connection pool size.
The default is 32. Change this value to 4*(number of threads). To change this value, edit the /etc/my.cnf file and increase the MySQL max_connection setting, for example, max_connections = 200.
If your migration using an LDAP filter produces an error like:
LDAP search failure: error result
then your filter might be too broad and you might be running into an LDAP search limit exceeded issue. Try narrowing down your filter. For example, if your filter was:
davadmin migration -X calmaster -L cs6.example.com:8080 -B "o=dirbase" -R "objectclass=icscalendaruser"
change it so that it resembles the following:
davadmin migration -X calmaster -L cs6.example.com:8080 -B "o=dirbase" -R "(&(uid="a*")(objectclass=icscalendaruser))"
If you use this approach, you need to run multiple migration commands to complete the migration for the entire directory.
If your migration produces errors similar to the following:
2010-04-19_151418/master_log:[user@host.example.com] Exception on creation of http://host-cs.example.com:80: Read timed out
then you might need to increase the timeout period for HTTP connections. To do so, change the davcore.serverlimits.httpconnecttimeout and davcore.serverlimits.httpsockettimeout parameters by using the davadmin config command.