This chapter describes how to administer the address book service in Oracle Communications Convergence provided by Convergence Server.
See "Enabling Core Services for Convergence" for information about enabling services.
The address book service can be also provided by Oracle Communications Contacts Server. See Contacts Server System Administrator's Guide for information about administering Contacts Server.
See Convergence Installation and Configuration Guide for information about configuring Convergence with Contacts Server.
Convergence server enables you to scale and support large number of users. Convergence server stores the information of a user's personal address book in the User/Group LDAP. This attribute is denoted by the psRoot attribute.
The psRoot is an attribute in the user's LDAP that specifies the host of the LDAP server, the port it is listening to port, and the DN where the Address Book entries for the user is stored. The psRoot attribute is in the form ldap://ldap_host:ldap_port/DN. The value of psRoot attribute determines the DB type and DB location.
For example of how a psRoot attribute looks in a user's LDAP entry:
ldap://siroe.com:389/piPStoreOwner=jsmith,o=siroe.com,o=PiServerDb
Where:
siroe.com:389 is the host name and port number of the LDAP server. In this example, the LDAP server listens to port 389.
piPStoreOwner=jsmith,o=siroe.com,o=PiServerDb specifies the DB of the Personal Store.
Note:
The address book server does not provide any utility to distribute psRoot values for users, according to any scalability policy. Administrators need to set a specific policy suited best for the organization and use custom scripts to set the psRoot value for that policy.The following are the key components of the Address Book Horizontal Scalability architecture:
Personal Store
DBMap
DB
A Personal Store stores the address book information of a user. It contains the definition of all the address books that a user has created, along with all the entries in those address books. Personal Stores are represented as URLs, which describe the directory instance in which they are located and the DN within that particular directory instance.
A DBMap is a collection of DBs of the same type.
A DB contains a collection of Personal Stores. The address book can access any number of DBs. Every DB is defined by an identifier in configuration file that defines the connection parameters for that DB. A DB of different type points to different DB locations.
The psRoot attribute can be turned on or off using the iwcadmin command-line interface by setting the ab.useuserpsroot to false. If set to false, Convergence uses the Default Server value that is set in the Convergence configuration.
Set ab.useuserpsroot to true to use the user's psRoot value. At runtime, the value of psRoot attribute is resolved to a directory instance using ldaphost and ldapport. Based on ldaphost and ldapport, the Identifier to the database will be resolved. Here Identifier is an arbitrary string that distinguishes one instance from the other.
When a new user logs in, default values are set for the psRoot attribute in the user's entry. For new users, a psRoot value is constructed by using the psRoot pattern and DefaultServer defined in the default configuration. For example, when you use the default psRoot pattern, the default psRoot value is in the format:
ldap://default_server_host:port/piPStoreOwner=%U,o=%D,o=PiServerDb
where:
%U is the login ID of the user. For example, jsmith.
%D is the domain of the user. For example siroe.com.
The following example shows how to configure horizontal scalability of address book in a deployment where there are two directory servers: ds1.siroe.com.
Use following commands to enable horizontal scalability:
To configure personal address book to use directory server ds1.siroe.com:
iwcadmin -o ab.pstore.[psidentifier1].ldaphost -v ds1.siroe.com iwcadmin -o ab.pstore.[psidentifier1].ldapport -v 389 iwcadmin -o ab.pstore.[psidentifier1].ldapbinddn -v "cn=Directory Manager" iwcadmin -o ab.pstore.[psidentifier1].ldapbindcred -v abbbbc
To configure personal address book to use directory server ds2.siroe.com:
iwcadmin -o ab.pstore.[psidentifier2].ldaphost -v ds2.siroe.com iwcadmin -o ab.pstore.[psidentifier2].ldapport -v 389 iwcadmin -o ab.pstore.[psidentifier2].ldapbinddn -v "cn=Directory Manager" iwcadmin -o ab.pstore.[psidentifier2].ldapbindcred -v aaaaabbbb
To enable horizontal scalability, you must set the ab.useuserpsroot configuration parameter to true:
iwcadmin -o ab.useuserpsroot -v true
To set the default server, you must set the ab.pstore.defaultserver configuration parameter to the personal store identifier:
iwcadmin -o ab.pstore.defaultserver -v psidentifier2
Where psidentifier2 is default server. If psRoot attribute is not present, ds2.siroe.com will be used for personal address book. When a new user logs in, default values are set for the psRoot attribute in the user's entry.
Convergence provides a notification module that enables administrators to plug-in a JMS based notification service. The notification module publishes messages to the configured JMS brokers.
Convergence provides a notification service for the Personal Address Book (PAB). The notification module publishes notification messages to a JMS broker when certain state changes occur in a user's PAB. The notification messages are published on a JMS topic or a queue that can be consumed by an appropriate consumer.
This technical note provides an overview of Convergence's address book notification service and provides information about how to configure the notification service.
This section provides information on the prerequisites for the working with this feature. The administrator must have working knowledge of the following products and technologies:
Administration knowledge of GlassFish Server - The administrator must create the JMS-based connection factories and destination resources.
Convergence Administration - The administrator must have working knowledge of administering Convergence.
To configure Convergence for address book notification service, you must perform the following high-level steps:
Set up the message queue notification service configuration parameters.
Choose a notification strategy.
Set the Convergence configuration parameters to set notifications.
To make use of the notification service in Convergence, you must first enable Convergence to use the notification service. To do this, enable the following Convergence parameters.
notify.service.enable - Set this parameter to true to enable the notification service.
iwcadmin -o notify.service.enable -v true
The address book notification service publishes notifications to multiple destinations. The destination can be a topic or a queue. Each destination is uniquely identified by a service name. The service name is then resolved Convergence and the notifications are sent to the destination based on the destination type, destination name, and the connection attributes of the service name.
The service name is any unique string. The service name acts as an identifier for a particular destination. For each service name, the various attributes such as the destination type, destination name, and the connection attributes must be set.
notify.mq.[serviceName].enable: Set this parameter to true to enable the notification service for a destination. For example:
iwcadmin -o notify.mq.[serviceName1].enable -v true
notify.mq.[serviceName].destinationtype: For each destination, the destination type must be set. The valid values are: TOPIC or QUEUE. For example:
iwcadmin -o notify.mq.[serviceName1].destinationtype -v TOPIC
notify.mq.[serviceName].destinationname: The destination name. This name must match the corresponding JMS connection in GlassFish Server. For example:
iwcadmin -o notify.mq.[serviceName1].destinationname -v destinationName1
notify.mq.[serviceName].connection: Connection attribute.
iwcadmin -o notify.mq.[serviceName1].connection -v JMS_connection_factory
notify.mq.[serviceName1].resourcetype: Specifies the resourcetype and needs to be set to producer for address book notifications to work
iwcadmin -o notify.mq.[serviceName1].resourcetype -v producer
If you do not set this parameter, address book notifications do not work as expected.
The values for the destinationtype, destinationname, and connection must be the same as the settings for the JMS resources: Connection Factory and JMS resources when configuring GlassFish Server.
Convergence provides various notification strategies. You can employ a notification strategy based on how you want to publish and broadcast the notifications. You can set up the following types of notification strategies:
User Specific Notification Use the user specific notification strategy to trigger notifications to be published based on the state changes of particular contacts in your address books. To enable notification for a per-user, you must set the abEventNotificationDestination attribute in the user's LDAP entry to the name of the destination to which the notifications must be published.
The user must have the SunUCPreferences object class available in the LDAP.
Notification for All Users To enable notification for all users, you must set the following parameters:
ab.pstore.notification.destination
ab.pstore.notification.notifyall
Domain Based Configuration If you want to trigger notifications to be published based on the domains, you must set the appropriate domain level attributes. For example:
iwcadmin -o ab.{siroe.com}.psrootpattern -v ldap:///piPStoreOwner=%U,o=%D,o=PiServerDb
iwcadmin -o ab.{siroe.com}.pstore.defaultserver -v myldap
iwcadmin -o ab.{siroe.com}.pstore.[myldap].ldaphost -v newLdap.siroe.com
iwcadmin -o ab.{siroe.com}.pstore.[myldap].ldapport -v 389
iwcadmin -o ab.{siroe.com}.pstore.[myldap].ldapbinddn -v 'cn=Directory Manager'
iwcadmin -o ab.{siroe.com}.pstore.[myldap].ldapbindcred -v password
The following example shows how to set domain level notifications. In this example, the triggers have been set on the Create Contact, Create Contact Photo, Delete Contact, and Modify Contact actions. You can set the triggers based on your requirements.
iwcadmin -o ab.{siroe.com}.pstore.notification.destination -v serviceName1
iwcadmin -o ab.{siroe.com}.pstore.notification.event.createcontact -v true
iwcadmin -o ab.{siroe.com}.pstore.notification.event.createcontactphoto -v true
iwcadmin -o ab.{siroe.com}.pstore.notification.event.deletecontact -v true
iwcadmin -o ab.{siroe.com}.pstore.notification.event.modifycontact - v true
iwcadmin -o ab.{siroe.com}.pstore.notification.notifyall -v true
Note:
You must restart the GlassFish Server on which Convergence is deployed after making the configuration changes.Table 6-1 lists the types of notifications provided by Convergence:
Table 6-1 Notification Triggers
| Notification Trigger | Configuration Parameter | Description |
|---|---|---|
|
Create Contact |
ab.pstore.notification.event.createcontact |
This parameter, when set to true, triggers a notification when a new contact is created. |
|
Delete Contact |
ab.pstore.notification.event.deletecontact |
This parameter, when set to true triggers a notification when a contact is deleted. |
|
Modify Contact |
ab.pstore.notification.event.modifycontact |
This parameter, when set to true, triggers a notification when a contact is modified. |
|
Create Contact Photo |
ab.pstore.notification.event.createcontactphoto |
This parameter, when set to true triggers a notification when a user adds a photo for a contact. |
This section provides information about the various configuration steps that need to be performed in GlassFish Server for the notification service to work. The JMS connection factory and destination resources must be set.
The following examples show how to create the JMS connection factory and destination resources. You can create these either using the-asadmin-command-line-utility or by using the Administration Console.
Create the JMS Connection Factory.
GlassFish_Home/bin/asadmin -u admin -p 4848 -passwordfile /export/pass create-jms-resource --restype javax.jms.TopicConnectionFactory --description "example of creating a JMS connection factory" jms/ConnectionFactory
Note:
To configure the JMS connection factory on a remote host, set the appropriate remote host options. Otherwise, the remote host will not receive JMS messages. For more information on setting remote host options, refer to the GlassFish Server help:
GlassFish_Home/bin/asadmin create-jms-resource - help
Create the JMS Destination Queue.
GlassFish_Home/bin/asadmin -u admin -p 4848 --passwordfile /export/pass create-jms-resource --restype javax.jms.Queue jms/Queue
Create the JMS Destination Topic.
GlassFish_Home/bin/asadmin -u admin -p 4848 --passwordfile /export/pass create-jms-resource --restype javax.jms.Topic jms/Topic
When configuring Convergence for notification, use the notification log levels to troubleshoot any problems that you encounter when working with this feature. You can set the log levels for the notification service. Using the iwcadmin command, you can set the logging levels for the log.NOTIFY.level parameter.
This section provides information about the format in which data is passed over as part of the notification message. The notification message must be used by the consumers of the notification service. The notification message contains the vCard of the user along with the following details:
message
domain
bookid
timestamp
uid
operation
entryid
The following is the data format of the notification sent when a new contact is created:
Message:BEGIN:VCARD VERSION:3.0 PROFILE:VCARD PRODID:Sun Address Book UID: FN:user1 N:d;user1;;; NICKNAME: ORG:siroe; TITLE:Mr ANNIVERSARYDATE:-- BDAY:-- TEL;TYPE=WORK,PREF: TEL;TYPE=HOME: TEL;TYPE=CELL: TEL;TYPE=PAGER: TEL;TYPE=FAX: EMAIL;TYPE=INTERNET;TYPE=WORK;TYPE=PREF:user1@siroe.com EMAIL;TYPE=INTERNET;TYPE=HOME: EMAIL;TYPE=INTERNET;TYPE=OTHER: ADR;TYPE=HOME:;;;;;; ADR;TYPE=WORK:;;;;;; ADR;TYPE=OTHER:;;;;;; NOTE: URL;TYPE=HOME: URL;TYPE=WORK: X-IMADDR1: X-IMSERVICE1:SunIM X-IMADDR2: X-IMSERVICE2:AIM CALURI: FBURL: END:VCARD domain siroe.com bookid e11dbf2a4c610 timestamp 20090524T205226Z uid ngc5 operation CreateContact entryid e12174653ce40
The following is the data format of the notification sent when a contact information is modified:
Modify Contact: =========== Message: BEGIN:VCARD VERSION:3.0 PROFILE:VCARD PRODID:Sun Address Book UID:e1218771a5d22 FN:user1 d N:d;user1;;; NICKNAME: ORG:sun; TITLE:mts ANNIVERSARYDATE:-- BDAY:-- TEL;TYPE=WORK,PREF: TEL;TYPE=HOME: TEL;TYPE=CELL: TEL;TYPE=PAGER: TEL;TYPE=FAX: EMAIL;TYPE=INTERNET;TYPE=WORK;TYPE=PREF:user2@siroe.com EMAIL;TYPE=INTERNET;TYPE=HOME:user2@siroe.com EMAIL;TYPE=INTERNET;TYPE=OTHER: ADR;TYPE=HOME:;;;;;; ADR;TYPE=WORK:;;;;;; ADR;TYPE=OTHER:;;;;;; NOTE: URL;TYPE=HOME: URL;TYPE=WORK: X-IMADDR1: X-IMSERVICE1:SunIM X-IMADDR2: X-IMSERVICE2:AIM CALURI: FBURL: END:VCARD domain siroe.com bookid e11dbf2a4c610 timestamp 20090524T205309Z uid ngc5 operation ModifyContact entryid e12174653ce40
The following is the data format of the notification sent when a contact is deleted:
Delete Contact: =========== Message: null domain siroe.com bookid e11dbf2a4c610 timestamp 20090524T205425Z uid ngc5 operation DeleteContact entryid e121746661f21
The following is the data format of the notification sent when a photo is assigned to a contact:
Message: R0lGODlhMgArAHAAACH/C05FVFNDQVBFMi4wAwEAAAAh/ glnaWY0ajEyMTYAIfkEBSAABwAsAAAAADIAKwCCAAAAAAD/AP8AhAAA/wAA//8AAAAAAAAAA/ 54utz+MMoJgb2W6n2L/ 961jY0FnmdGcgDqfuoqtW8dyhFt2wDZP7qdyfWjAATFxVDYQcVmSEeQ13RqjsnDNKXD1LKM3hEZ28Ka3hd YgUW6o9ovumoFtgX4n/ m8XKoreIFFeyF0OwVrbIJhVH6HiWxPcVSHKTMqaZWaiJBaGIaEX1ySYRiTMJuoIJ8cTqlbYiJXrpWwSqQV To5cRLcjUwAEwru7MJG4uSHCBMHMnzxKeb80zc3Mmpimv8rL19iRiz7c3rXg4eKcoZaKY3ArxXKlbZ2X2G usOMdqyPkVn58DZPUzwk/gwBz8jh28RM/gQnkF/ y38FOBCRSABKmbMmCdwQruNIC+WCLmRjIyPIc8pCkTS3a9AMAVJwhBT5bR/ HT3hfMizQQIAIfkEBSAABwAsAAAAADIAKwCCAAAAAAD/AP8AhAAA/wAA//8AAAAAAAAAA/ 54utz+MMqpgL2W6n2L/ 961jY0FnmdGcgDqfuoqtW8dyhFt2wDu6CkgD9LTmFCYXajIAAiYs1dSWYBWnhQhaFrVbkvYiXd55CIXFwH W2qxNzanrc+5kH8YwHTx+V6vrdngue19yfnZ3VHlHUk2HOYp5O1YiRIKRQSqVJR1bmCGZGIFwl4Nxog8Yi SmYWoicTK6KriMxXoyDuDdGlXi6XQTBQq9gYatSosLBBHq1qnelIcsAwku1h0XR0svMuxx+T9mR1NVVK0 5/xtpdNMREdDHQre6Wm03a8T4zv2T6LAADRAn0x+uVPYKp8v1QiBANw3v0ZAg0+ KyhhQAYAwDAGCxI40VUOCwIyEhS44+SGR9JHFkSHCU/KFWSQAfuz8E0NV1KnEiP58O GQBkkAAA7 domain siroe.com bookid e1223b29da380 timestamp 20090702T111156Z uid ngc2 operation SetContactPhoto entryid e1223b29daad1
To configure Personal Address Book to use directory server other than user group directory server, set the following configuration parameters:
ab.pstore.[identifier].ldaphost - Set this parameter to the host name of the LDAP server.
ab.pstore.[identifier].ldapport - Set this parameter to the port number on which the LDAP server listens.
ab.pstore.[identifier.ldapbinddn - Set this parameter to the LDAP bind dn value of the LDAP server.
ab.pstore.[identifier].ldapbindcred - Set this parameter to the Bind credentials of the LDAP server.
The following example shows the configuration parameter settings:
iwcadmin -o ab.pstore.[psidentifier1].ldaphost -v host.siroe.com iwcadmin -o ab.pstore.[psidentifier1].ldapport -v 400 iwcadmin -o ab.pstore.[psidentifier1].ldapbinddn -v "cn=Directory Manager" iwcadmin -o ab.pstore.[psidentifier1].ldapbindcred -v dmcredentials
Personal store can be configured with multiple directory servers. In this example psidentifier1 is used to identify personal store configuration for siroe.com.
If the configured directory server needs to act as the personal store's default server, then set the ab.pstore.defaultserver configuration parameter. For example:
iwcadmin -o ab.pstore.defaultserver -v psidentifier1
To configure corporate directory to use directory server other than user group directory server, set the following configuration parameters:
ab.corpdir.[identifier].ldaphost
ab.corpdir.[identifier].ldapport
ab.corpdir.[identifier].ldapbinddn
ab.corpdir.[identifier].ldapbindcred
The following example has the configuration parameters settings:
iwcadmin -o ab.corpdir.[identifier].ldaphost -v host.siroe.com iwcadmin -o ab.corpdir.[identifier].ldapport -v 400 iwcadmin -o ab.corpdir.[identifier].ldapbinddn -v "cn=Directory Manager" iwcadmin -o ab.corpdir.[identifier].ldapbindcred -v xyzxyz
Where identifier identifies the corporate directory configuration for host.siroe.com. For a single corporate directory configuration, you must use default as the identifier.
See "Setting Up Multiple Corporate Directories" for information about configuring and enabling multiple corporate directories.
To enable autocomplete of email address for Corporate Directory, you must set the client.enablecorpabautocomplete configuration parameter to true.
iwcadmin -o client.enablecorpabautocomplete -v true
Note:
The search results will appear in the Convergence client, after the first three characters of the name or email address are typed.You can set up a domain based configuration for Personal Address Book and Corporate Directory.
To set up domain-based configuration for Personal Address Book, set the following parameters by using the iwcadmin command:
ab.{identifier}.psrootpattern
ab.{identifier}.pstore.defaultserver
ab.{identifier}.pstore.[domain].ldaphost
ab.{identifier}.pstore.[domain].ldapport
ab.{identifier}.pstore.[domain].ldapbinddn
ab.{identifier}.pstore.[domain].ldapbindcred
The following example shows the configuration parameter settings:
iwcadmin -o ab.{domain.com}.psrootpattern -v ldap:///piPStoreOwner=%U,o=%D,o=PiServerDb
iwcadmin -o ab.{domain.com}.pstore.defaultserver -v domainid1
iwcadmin -o ab.{domain.com}.pstore.[domainid1].ldaphost -v host.xyz.com
iwcadmin -o ab.{domain.com}.pstore.[domainid1].ldapport -v 400
iwcadmin -o ab.{domain.com}.pstore.[domainid1].ldapbinddn -v "cn=Directory Manager"
iwcadmin -o ab.{domain.com}.pstore.[domainid1].ldapbindcred -v xyzcred
Where domain.com is the domain (within curly braces).
All the configuration data for the domain domain.com is grouped in to one logical set identified by using the identifier domainid1.
The example shows the minimum set of configuration parameters that you need to set for the domain based configuration for Personal Address Book. However, you can set other configuration parameters.
To set the lookthrulimit to 2000 for Personal Address Book in domain domain.com, type the following command:
iwcadmin -o ab.{domain.com}.pstore.lookthrulimit -v 2000.
To set up domain-based configuration for Corporate Directory:
Set the following configuration parameters:
ab.{identifier}.corpdir.[domain].urlmatch
ab.{identifier}.corpdir.[domain].searchattr
ab.{identifier}.corpdir.[domain].lookthrulimit
ab.{identifier}.corpdir.[domain].ldaphost
ab.{identifier}.corpdir.[domain].ldapport
ab.{identifier}.corpdir.[domain].ldapbinddn
ab.{identifier}.corpdir.[domain].ldapbindcred
For example:
iwcadmin -o ab.{domain.com}.corpdir.[corpdomainid1].urlmatch
-v ldap://corp-directory1
iwcadmin -o ab.{domain.com}.corpdir.[corpdomainid1].searchattr
-v entry/displayname,@uid
iwcadmin -o ab.{domain.com}.corpdir.[corpdomainid1].lookthrulimit
-v 3000
iwcadmin -o ab.{domain.com}.corpdir.[corpdomainid1].ldaphost
-v host.abc.com
iwcadmin -o ab.{domain.com}.corpdir.[corpdomainid1].ldapport
-v 389
iwcadmin -o ab.{domain.com}.corpdir.[corpdomainid1].ldapbinddn
-v "cn=Directory Manager"
iwcadmin -o ab.{domain.com}.corpdir.[corpdomainid1].ldapbindcred
-v abcabc
Where domain.com specifies the domain. All the configuration data for the domain domain.com is grouped in to one logical set identified by using identifier corpdomainid1.
Note:
The value for the urlmatch configuration parameter must be unique. Format for urlmatch is ldap://unique_value or ldap://host:port/DN e.g. ldap://corp-directory1 ,ldap://corporatedirectory2, ldap://somehost:390/ou=people,o=ab.org etc.First time when user does address book operation (apart from login.wabp), corporate directory entry (under piPStoreOwner=user, o=domain, o=PiServerDb) with piRemotePiURL attribute value as urlmatch gets created. After this if urlmatch is changed, either delete such entries so that this entry gets created when first AB command is issued or update corporate directory entry for all users with new urlmatch value.
Copy dictionary-locale.xml (for example: dictionary-en.xml) from Convergence_Home/config/templates/ab/domain/defaultps to Convergence_Home/config/templates/ab/domain/domain-directory. The dictionary-locale.xml file can be updated in order to change or to customize display name and description.
In some cases, you might want to disable your corporate directory in certain domains. To do so, follow these steps:
Set both personal address book and Corporate Directory settings as described in "Setting Up Domain-Based Configuration for Address Book".
Disable the Corporate Directory for the specific domain:
iwcadmin -o ab.{domain.com}.corpdir.[default].enable" -v false
Restart the Oracle certified application server.
Note:
You can ignore errors or exceptions in the log files.To change the default corporate directory search filter, set the ab.corpdir.[identifier].searchfilter configuration parameter with the search criteria you want to base your corporate directory searches on.
The following example shows the usage of search customization:
iwcadmin -o ab.corpdir.[default].searchattr -v entry/displayname,@uid,person/surname iwcadmin -o ab.corpdir.[default].searchfilter -v '(&(&([filter])(|(objectClass=GROUPOFUNIQUENAMES)(objectClass=GROUPOFURLS) \\ (objectClass=ICSCALENDARRESOURCE)(objectClass=INETORGPERSON)))(objectClass=*))'
Where [filter] is replaced with the search generated by the ab.corpdir.[identifier].searchattr configuration option.
The example produced the following LDAP output in the corporate LDAP directory access logs when an end-user searched for "bob":
[13/Oct/2008:11:51:54 +1100] conn=686404 op=30 msgId=576 - SRCH base="o=sun.com,o=isp" scope=2 filter="(&(&(|(|(cn=bob*)(uid=bob*))(sn=bob*))(|(objectClass=GROUPOFUNIQUENAMES)(objectClass=GROUPOFURLS) (objectClass=ICSCALENDARRESOURCE)(objectClass=INETORGPERSON)))(objectClass=*))" attrs="objectClass createTimestamp cn uid description mail multiLineDescription modifyTimestamp"
Follow these steps to configure Convergence to make use of virtual list view (VLV):
Configure Directory Server with VLV. For more information on creating and managing browsing indexes in Directory Server:
See Directory Server Administration Guide.
Set the VLV filter and scope in the corporate directory.
iwcadmin -o ab.corpdir.[default].vlvfilter -v "(&(mail=*)(cn=*))" iwcadmin -o ab.corpdir.[default].vlvscope -v 2
Enable the ab.corpdir.[default].vlvpaging configuration parameter to true.
iwcadmin -o ab.corpdir.[default].vlvpaging -v true
Convergence supports the following vCard standards:
vCard 2.1
vCard 3.0
Convergence supports the following encoding formats for importing and exporting vCard:
UTF-8
ISO-8859-1
BIG5
EUC-CN
EUC-JP
EUC-KR
SHIFT_JIS
Convergence supports the following locales by default:
English
Japanese
French
German
Spanish
Korean
Traditional Chinese
Simplified Chinese
For each locale, configuration parameters for import and export exist in the Convergence server. By default, these configuration parameters are assigned a character encoding when you install Convergence.
Table 6-2 shows the default encoding formats for locales when Convergence is installed. The table also lists the configuration parameters that are assigned for storing the import and export preference for the locale.
Table 6-2 Supported Default vCard Locales
| Locale | Encoding | Import Parameter | Export Parameter |
|---|---|---|---|
|
English |
UTF-8 |
ab.import.vcard.misc.en |
ab.export.vcard.misc.en |
|
Japanese |
UTF_8 |
ab.import.vcard.misc.ja |
ab.export.vcard.misc.ja |
|
French |
UTF-8 |
ab.import.vcard.misc.fr |
ab.export.vcard.misc.fr |
|
German |
UTF-8 |
ab.import.vcard.misc.de |
ab.export.vcard.misc.de |
|
Korean |
UTF-8 |
ab.import.vcard.misc.ko |
ab.export.vcard.misc.ko |
|
Traditional Chinese |
UTF-8 |
ab.import.vcard.misc.zh-tw |
ab.export.vcard.misc.zh-tw |
|
Simplified Chinese |
UTF-8 |
ab.import.vcard.misc.zh-cn |
ab.export.vcard.misc.zh-cn |
In the previous table, the character encoding for English is set to UTF-8. This setting means that when you import or export vCard contacts to or from the Convergence client, the vCard entries are imported or exported in the UTF-8 format character set. In this case, UTF-8 is the default setting for English users.
To enable the Convergence client to import or export vCard entries to other character sets, set the address book vCard configuration parameter in the Convergence server.
Type the iwcadmin command to set the import and export character set preferences for the configuration parameters of the locale. This command enables you to change the character set encoding for importing or exporting vCard entries.
To change the character encoding for the Japanese user vCard from UTF-8 to Shift_JIS for example, set the corresponding configuration parameters for import and export.
To set the character encoding to import vCard entries for the Japanese locale, type the following command:
iwcadmin -o ab.import.vcard.misc.ja -v Shift_JIS
To set the character encoding to export vCard entries for the Japanese locale, type the following command:
iwcadmin -o ab.export.vcard.misc.ja -v Shift_JIS
The vCard entries are imported or exported in the Shift_JIS encoding character set.
Note:
You must set the same character set encoding for both import and export for a locale.vCard 3.0 enables users to include photos in their contacts. By default, Convergence does not import or export photos of your contacts. If you want photos to be imported or exported, you must enable the ab.exportphoto and ab.importphoto configuration parameters.
To enable exporting of contacts with photo in Vcard 3.0 format, type the following command:
iwcadmin -o ab.exportphoto -v true
To import contacts with photo in Vcard 3.0 format, type the following command:
iwcadmin -o ab.importphoto -v true
When looking in the Corporate Directory of the default domain all the administrative accounts are being displayed. These can be hidden by using psIncludeInGAB attribute in the ldap server. The default value of this attribute is true.
If you want to hide users in the Corporate Directory, set in a first step the psIncludeInGAB attribute to false for these users. Next, the corporate directory search filter needs to exclude these users with their psIncludeInGAB attribute set to false. For example:
iwcadmin -o ab.corpdir.[default].searchfilter -v '(&([filter])(!(psIncludeInGAB=false)))'
If a contact has been deleted by the end user, Convergence determines what do to with that information based on how you set the ab.pstore.deleteperm configuration parameter. If you set the parameter to true, the contact is deleted from the user's personal address book entries on Directory Server. If, however, you set ab.ps.deleteperm to false, the following attribute/value pair is added to the deleted contact in Directory Server:
delete: true
The contact no longer appears in Convergence as if it were permanently deleted from the Directory Server.
This task can be particularly useful when you are synchronizing deleted contact entries in Microsoft Outlook and Convergence when using Connector for Microsoft Outlook.
Virtual List View (VLV) index, also known as browsing index, is similar to indexes or views in a database. Create the VLV indexes to reduce the time taken to search the LDAP entries. If a Directory Server deployment contains several LDAP entries, then searching the entries takes considerably more time. Directory Server enables you to create indexes that reduce the search time.
You must set the following parameters in the LDIF file to enable VLV indexes in the directory server.
search_base
vlv_search_filter
vlv_sort_attribute
vlv_scope
If multiple back-end user/group Directory Servers are configured for a system, you will need to create indexes for each user/group Directory Server instance.
You require the Directory Server settings information before setting the VLV browsing indexes. Directory Server settings are present in the dse.ldif file in the DS_Home/config directory (where DS_Home is the directory in which the directory server software is installed). Note the value of the cn attribute.
The following is a code sample of the dse.ldif file:
dn: cn=isp,cn=ldbm database,cn=plugins,cn=config objectClass: top objectClass: extensibleObject objectClass: nsBackendInstance cn: isp creatorsName: cn=directory manager modifiersName: cn=directory manager entrydn: cn=isp,cn=ldbm database,cn=plugins,cn=config numSubordinates: 4 nsslapd-suffix: o=isp nsslapd-cachesize: -1 nsslapd-cachememsize: 10485760 nsslapd-readonly: off nsslapd-require-index: off nsslapd-directory: /var/opt/SUNWdsee/dsins1/db/isp
Create two files in a temporary location after you identify the required Directory Server setting entries. For example, tmp1.vlv and tmp2.vlv. These files must contain information about various indexes and search options that you can create on Directory Server.
The temp1.vlv file should have the following parameters.
dn: cn=browsing_index,cn=database_name,cn=ldbm database,cn=plugins,cn=config changetype: add objectClass: top objectClass: vlvSearch cn: browsing_index vlvbase: o=isp vlvscope: 2 vlvfilter: (&(mail=*)(cn=*)) aci: (targetattr="*")(version 3.0; acl "VLV for Anonymous"; allow (read,search,compare) userdn="ldap:///anyone";)
Table 6-3 lists the parameters for temp1.vlv.
Table 6-3 Configuration Parameters for temp1.vlv File
| Parameters | Description |
|---|---|
|
browsing-index |
Any name |
|
database-name |
Same as the existing database name that is given when directory server is configured by running directory preparation tool (comm_dssetup.pl). This database name should not be changed. |
|
vlvbase |
Value from which you want the search to proceed. For example, instead of dc=example,dc=siroe,dc=com you can provide a subtree o=example.siroe.com,dc=example,dc=siroe,dc=com. |
|
vlvscope |
Similar to the LDAP protocol scoping number: 0 -Indicates searching only the base level entry 1 - Indicates searching only the entries at one level below the search base. If you set vlvScope to 1, you must create a vlvSearch or vlvIndex for each organization unit (ou) where you want a VLV index. 2 - Indicates searching of the entries at all levels and all its descendants. |
|
vlvfilter |
Filter that is used to match and filter results. When you perform a search, only those LDAP entries that have both mail and cn attributes defined are returned. Some of the entries might not have mail attribute. If they do not have the mail attribute, modify the vlvfilter as (|(mail=*)(cn=*)). The OR operator is used instead of the AND operator. Only include contacts (for example: objectclass=inetorgperson) while creating the VLV index so that the address book search excludes groups, resources and any other entries that are not contacts. This is mandatory for Convergence 2. Leave an extra blank line after the last line in both the temp1.vlv and temp2.vlv files to make sure that all the entries in the files are read when the LDAP is modified. |
The temp2.vlv file should have the following parameters:
dn: cn=Sort by cn,cn=browsing_index,cn=database_name,cn=ldbm database,cn=plugins,cn=config changetype: add objectClass: top objectClass: vlvIndex cn: Sort by cn vlvSort: cn
The temp1.vlv and temp2.vlv files specify what to index and the parameter by which results must be sorted. You need to create multiple indexes by creating the following files: temp3.vlv, temp4.vlv, temp5.vlv, temp6.vlv, temp7.vlv, temp8.vlv, and temp9.vlv.
The temp3.vlv file should have the following parameters:
dn: cn=Reverse Sort by cn,cn=browsing_index,cn=database_name,cn=ldbm database,cn=plugins,cn=config changetype: add objectClass: top objectClass: vlvIndex cn: Reverse Sort by cn vlvSort: -cn
The temp4.vlv file should have the following parameters:
dn: cn=Sort by sn,cn=browsing_index,cn=database_name,cn=ldbm database,cn=plugins,cn=config changetype: add objectClass: top objectClass: vlvIndex cn: Sort by sn vlvSort: sn
The temp5.vlv file should have the following parameters:
dn: cn=Reverse Sort by sn,cn=browsing_index,cn=database_name,cn=ldbm database,cn=plugins,cn=config changetype: add objectClass: top objectClass: vlvIndex cn: Reverse Sort by sn vlvSort: -sn
The temp6.vlv file should have the following parameters:
dn: cn=Sort by mail,cn=browsing_index,cn=database_name,cn=ldbm database,cn=plugins,cn=config changetype: add objectClass: top objectClass: vlvIndex cn: Sort by mail vlvSort: mail
The temp7.vlv file should have the following parameters:
dn: cn=Reverse Sort by mail,cn=browsing_index,cn=database_name,cn=ldbm database,cn=plugins,cn=config changetype: add objectClass: top objectClass: vlvIndex cn: Reverse Sort by mail vlvSort: -mail
The temp8.vlv file should have the following parameters:
dn: cn=Sort by givenname,cn=browsing_index,cn=database_name,cn=ldbm database,cn=plugins,cn=config changetype: add objectClass: top objectClass: vlvIndex cn: Sort by givenname vlvSort: givenname
The temp9.vlv file should have the following parameters:
dn: cn=Reverse Sort by givenname,cn=browsing_index,cn=database_name,cn=ldbm database,cn=plugins,cn=config changetype: add objectClass: top objectClass: vlvIndex cn: Reverse Sort by givenname vlvSort: -givenname
To modify the LDAP using tmp1.vlv and tmp2.vlv enter the following command:
ldapmodify -h directory_server_fully_qualified_host_name -p directory_server_port -D "cn=Directory Manager" -f path/temp1.vlv ldapmodify -h directory_server_fully_qualified_host_name -p directory_server_port -D "cn=Directory Manager" -f path/temp2.vlv
Similarly, you can modify the LDAP by using all other VLV files:
Generate the indexes for the settings to take effect. Perform the following steps during a scheduled change window to restart Directory Server.
Perform the following steps to generate the indexes:
Change the directory to the Directory Server installation.
cd /opt/SUNWdsee/ds6/bin
Stop the Directory Server instance.
dsadm stop /var/opt/SUNWdsee/dsins1/
Populate the index entries by using the dsadm reindex command. The reindex option requires you to provide the vlv_sort_attribute, the path to the Directory Server instance, and the value of the user group base.
dsadm reindex -l -t "Sort by cn" /var/opt/SUNWdsee/dsins1/ "o=isp"
Start the Directory Server instance.
dsadm start /var/opt/SUNWdsee/dsins1/
If you require multiple sort attributes for tmp3.vlv and tmp4.vlv, generate indexes for each of cn, sn, and mail.
You need to configure Convergence to use the indexes after generating the indexes for Directory Server. Using the iwcadmin command, set the following Convergence parameters:
ab.corpdir.[default].vlvfilter
ab.corpdir.[default].vlvscope
ab.corpdir.[default].vlvpaging
ab.corpdir.[default].vlvsortby
ab.corpdir.[default].vlvsearchbase
ab.corpdir.[default].vlvsortby
For example:
iwcadmin -u admin_user_id -o ab.corpdir.[default].vlvfilter -v "(&(mail=*)(cn=*))"
iwcadmin -o ab.corpdir.[default].vlvscope -v 2
iwcadmin -o ab.corpdir.[default].vlvpaging -v true
iwcadmin -o ab.corpdir.[default].vlvsortby -v "entry/displayname,person/surname,email,person/givenname"
iwcadmin -o ab.corpdir.[default].vlvsearchbase -v "o=isp"
Note:
The value for ab.corpdir.[default].vlvfilter is (&(mail=*)(cn=*)). This value should exactly match with the value provided in the Directory Server settings and the match should be a string match. It cannot even be (&(cn=*)(mail=*)) because interchanging the mail and cn attributes causes a mismatch with the settings in the Directory Server.The default corporate directory is used in the previous commands. The same set of commands apply to the nondefault corporate address book ab.corpdir.[identifier].vlvscope or the domain based corporate address book ab.{identifier}.corpdir.[domain].vlvscope.
The purpose of the parameter vlvsortby is that in case the server does not receive any sortby attribute from the client, the search results are sorted by the value set for this parameter. This applies only when VLV is setup.
You must restart the application after making any configuration changes in Convergence.
When you search a Corporate Address Book, you will see a drop down list in the Convergence client interface with the following search attributes:
Display name
First name
Last name
You must have VLV indexes set up for these attributes to work. If VLV is not set, the default search is done by Display name.
Note:
Convergence can be configured to enable address book service using both Convergence (WABP) and Contacts (NAB) servers and it is called co-existence mode. In this mode of configuration some users may be using WABP and others might have been migrated to NAB. You need to set the nab.nabuserattr parameter to an LDAP attribute used in the user entry to indicate that the user has been migrated to NAB. The default value of this attribute is nabStore (defined as part of nabUser ObjectClass). If this attribute is not present in user LDAP entry then it indicates that you are a WABP user and not a NAB user.
iwcadmin -o nab.nabuserattr -v user_attribute
See "Convergence Properties Reference" for information on nab.nabuserattr.
To verify VLV settings:
For the VLV search to be active when you search the corporate directory, the following four entities sent by the Convergence server should match with the values in Directory Server:
Search base
Search scope
VLV filter
Sort attribute
Convergence only supports cn.
Log in to Convergence and type a search command in the corporate directory to check the Directory Server access log files. The two cases A and B with corresponding access log files of Directory Server are shown:
ldapsearch -D "cn=Directory Manager" -w password -b dc=example,dc=com -x -S cn -G "0:3:name1" "(|(mail=*)(cn=*))" sn cn
Directory Server Access Log file A
[02/Dec/2008:12:46:52 +0100] conn=53 op=1 msgId=2 - SRCH base="dc=example,dc=com" scope=2 filter="(|(mail=*)(cn=*))" attrs="sn cn" [02/Dec/2008:12:46:52 +0100] conn=53 op=1 msgId=2 - SORT cn [02/Dec/2008:12:46:52 +0100] conn=53 op=1 msgId=2 - VLV 0:3:rao 128:156 (0) [02/Dec/2008:12:46:52 +0100] conn=53 op=1 msgId=2 - RESULT err=0 tag=101 nentries=4 etime=0
ldapsearch -D "cn=Directory Manager" -w password -b dc=example,dc=com -x -S sn -G "0:3:name1" "(|(sn=*)(cn=*))" sn cn
Directory Server Access Log file B
[02/Dec/2008:12:45:34 +0100] conn=52 op=1 msgId=2 - SRCH base="dc=example,dc=com" scope=2 filter="(|(sn=*)(cn=*))" attrs="sn cn" [02/Dec/2008:12:45:34 +0100] conn=52 op=1 msgId=2 - SORT sn (156) [02/Dec/2008:12:45:34 +0100] conn=52 op=1 msgId=2 - VLV 0:3:name1 97:156 (0) [02/Dec/2008:12:45:34 +0100] conn=52 op=1 msgId=2 - RESULT err=0 tag=101 nentries=4 etime=0 notes=U
Searches in A and B might vary based on the -S sort attribute. In this case, VLV is setup with cn as the sort attribute.
VLV index is used only if vlvSort, vlvbase, vlvscope, and vlvfilter are matched with the given attributes. In case A all the attributes are matched. Hence the VLV index is used. In case B the VLV Index is not used as the sort attribute passed is sn whereas the setup has cn. See the notes=U in the Log file B displays that the search was unindexed. You can still continue to search with the -S server sort option. It will always be unindexed if no VLV Index is present that matches the specific search. Also notice the line "VLV 0:3:rao" which means that a VLV search was performed and from the point where a match was found 3 other entries were returned apart from the match. The zero before 3 signifies that no entries above the match in the sort order are returned.
For example, assume that the Directory Server has a VLV in the following sorted order:
person1 age1 address1 email1@siroe.com person2 age2 address2 email2@siroe.com person3 age3 address3 email3@siroe.com person4 age4 address4 email4@siroe.com person5 age5 address5 email5@siroe.com person6 age6 address6 email6@siroe.com person7 age7 address7 email7@siroe.com person8 age8 address8 email8@siroe.com
Search for cn=person4 with the range as 1:3:person4.
person1 age1 address1 email1@siroe.com
person2 age2 address2 email2@siroe.com
person3 age3 address3 email3@siroe.com <-----
Search match ---> person4 age4 address4 email4@siroe.com |
person5 age5 address5 email5@siroe.com | Range of results returned
person6 age6 address6 email6@siroe.com |
person7 age7 address7 email7@siroe.com <-----
person8 age8 address8 email8@siroe.com
Since you have searched for 1:3:person4, the results returned are one entry before the match, three entries after the match, and the match entry itself. To verify, type the following command on the Directory Server to view the results:
ldapsearch -h directory_server_fully_qualified_host_name -p directory_server_port -TD "cn=directory manager" -w directory_manager_password -b search_base -s search_scope -x -S sort_attribute -G "number_of_results_before_match:number_of_results_after_match:search_string" vlv_filter
For example:
ldapsearch -h siroe.com -TD "cn=directory manager" -w password -b "dc=siroe,dc=siroe,dc=com" -s sub -x -S cn -G "1:3:person4" "(&(mail=*)(cn=*))"
The results displayed should match the results in Convergence.
The parameters ab.corpdir.[CommSuite:default].searchattr and ab.corpdir.[CommSuite:default].searchfilter are not involved in the VLV search.
Same as the existing database name that is given when directory server is configured by running directory preparation tool (comm_dssetup.pl). This database name should not be changed.