Configuring WebSphere Portal Collaboration Center People Finder portlet

Configuring the WebSphere Portal Collaboration Center People Finder portlet

by Tara Hall
with Sam Alexander

Level: All
Works with: WebSphere Portal Collaboration Center
Updated: 02-Jun-2003

IBM WebSphere Portal Collaboration Center is a collection of components that integrate QuickPlace, Sametime, and your LDAP directory into WebSphere Portal. As the name implies, Collaboration Center provides instant collaboration for Portal with these out-of-the-box portlets:

My Lotus Team Workplaces
My Lotus Team Workplaces shows you a list of the Team Workplaces (that is, QuickPlaces) to which you belong and lets you search across those Team Workplaces. It also lets you create and manage Team Workplaces from the Portal.
Lotus Web Conferencing
The Lotus Web Conferencing portlet uses Sametime meeting technology to let you schedule and participate in online meetings. You can also search for online meetings using this portlet.
People Finder
The People Finder portlet lets you search a corporate directory. This portlet can connect to any LDAP directory server, like Sun ONE Directory Server (formerly iPlanet Directory Server), IBM Directory Server, or Domino Directory.

The People Finder portlet is the only customizable portlet available in Collaboration Center, so you can configure it to suit the needs of your organization. The People Finder portlet is configurable both through an XML configuration file referred to as the directory connection and through the portlet user interface. This article describes how to configure the Collaboration Center People Finder portlet. We cover how to connect the People Finder portlet to your corporate LDAP directory server using an XML configuration file and how to configure the People Finder portlet through the People Finder Configuration. This article is intended for experienced LDAP directory administrators. Knowledge of XML is assumed.

The People Finder portlet
The People Finder portlet is based in part on an IBM intranet application known as BluePages that lets IBMers search for others in the organization using identifying information, such as first and last name, Internet address, serial number, and so on. The following screen shows the IBM BluePages application.

Like the BluePages application, the People Finder portlet lets you search for people within your organization by name, phone number, email address, and so on. An Advanced Search option is available for a more detailed search. Both the Quick Search that you are presented with when you first open Collaboration Center and the Advanced Search form are customizable. We'll talk more about that later in this article.

In addition to retrieving contact information, the BluePages application also provides organizational hierarchy information (that is, it lists who reports to the same manager as the person selected and the report-to-chain for the selected person). Similarly, the People Finder portlet can show organizational hierarchy information when you select the Show in Organization View option. (This option, along with the Show Person Record and Send E-mail options, is available when you click the user's name.) To display information in the Organization view, you first must set up the LDAP directory server. You can add a reporting hierarchy using the common attribute Manager that is used in the XML configuration file.

Organization View in the People Finder portlet

Organization View in the People Finder portlet

The Person Record lists contact, job-related, and background information. Like the Advanced Search form, the Person Record is also customizable. You can specify which fields to display in the Person Record. People Finder is the only Collaboration Center portlet that you can configure through WebSphere Portal. Later in this article, we cover how to configure the portlet, but before we can configure the portlet, we must connect the portlet to an LDAP directory.

Directory Connector for People Finder
Directory Connector for People Finder is the application that connects the People Finder portlet to your LDAP directory server. Directory Connector is a WebSphere application (EAR file) that you install on the WebSphere Portal/WebSphere Application Server (WAS) when you install Collaboration Center. The Directory Connector uses a DB2 or Oracle data store and the SQL programming language to retrieve data.

Using an XML configuration file, you define which LDAP directory server you want to connect People Finder to. (You do not need to install any Collaboration Center components on your LDAP directory server.) The XML configuration file is created automatically when you install Collaboration Center on WebSphere Portal. You can configure the XML file to access a specific LDAP URL, to specify the baseDN, and to modify the exposed attributes and their labels. You can change the labels of the exposed attributes, add attributes from your LDAP scheme, or remove attributes. Collaboration Center supports the inetOrgPerson object class, which we talk about later in this article.

To open the Directory Connector, go to:

http://Serverhostname/PFDirectoryConnector

where Serverhostname is the name of the server on which you installed WebSphere Portal Collaboration Center.

To change settings in People Finder, export the existing XML file named PFSampleConnection. Use a text editor, like Notepad, to modify the file, then import the file into Directory Connector. (Note that the first import often fails, but if you retry the import, it will work.) Directory Connector validates the file by verifying that the exposed attributes exist in the scheme of the specified LDAP server. After you validate the file, you can activate it. When the file is activated, the People Finder portlet is connected to the LDAP directory server.

Directory Connector for People Finder

The XML configuration file
The XML configuration file contains several sections:

Connection settings
Exposed attributes
Exposed filters
Exposed custom queries
Exposed recursive queries

The connection settings section defines the connections to the LDAP directory and includes required elements described in the following table.

Element	Description
hostURI	A fully qualified LDAP URL that follows the syntax: ldap://hostname:389 in which :389 is the default port on which the LDAP server listens.
baseDN	The "root directory" of your LDAP server where you want to search; this can include your entire organization or a subset of the organization.
bindDN	The name of a user with access rights to read data from the LDAP server; you can leave this element empty to bind anonymously. To bind a specific user, you must specify the fully-qualified name or distinguished name: cn=username,ou=orgunit,o=organization If you specify a user for the bindDN, provide privateCredentials (that is, specify a password) and change the securityProtocol element from none to simple.

The exposed attributes list all the fields that can be set up in the People Finder Configuration explained later in this article. The entries for exposed fields associate a meaningful label with an exposed field. The exposed custom queries section is used for Quick Search, which is also discussed later in this article. The exposed Custom Query is a specialized query that is more complex than the one field queries. The By Name custom query allows a single search against the FirstName, LastName, and NickName fields. The exposed recursive query is the ReportsTo query that builds the reports to chain and is set up to recursively search the Person Record based on the entry in the Manager field.

inetOrgPerson object class
Collaboration Center supports the inetOrgPerson object class for mapping fields from an existing LDAP directory to the People Finder portlet. Note that you can use People Finder without a schema. The inetOrgPerson object class defines individuals associated with an organization. This object class contains a number of attributes specifically intended for Internet/intranet directory deployments. For a complete description of the inetOrgPerson object class and its attributes, see rfc2798—Definition of the inetOrgPerson LDAP object class.

To map to an attribute in your LDAP scheme, you can modify the XML configuration file. The XML file lists the attribute label, a description, the mapped attribute name, and the attribute type. Here is an example:

<exposedAttribute label="DisplayName">

<mappedAttribute>displayName</mappedAttribute>

<type>String</type>

</exposedAttribute>

After you make changes, you can import the file into Directory Connector. You can either update the existing XML file or import a new XML file. After you import or update the file, click Validate to ensure that the XML is valid. After validating the file, click Activate to enable People Finder.

Configuring the People Finder portlet
After connecting People Finder to your LDAP directory, users can immediately begin searching your corporate directory. Note that Collaboration Center supports multiple directories, so you can configure it to use one directory for authentication and another directory for searching. However, details of that implementation is beyond the scope of this article.

As mentioned earlier, the People Finder portlet is the only customizable Collaboration Center portlet. A wrench icon in the upper right corner of the portlet means that you can configure it. (Both the Team Workplaces and Web Conferencing portlets are editable, but you cannot configure them.)

The following sections describe the different areas that you can configure, including the Person Record and Advanced Search form.

Configuration Basics
Before you configure any other part of the People Finder portlet, you must complete the Configurations Basic settings. Click the wrench icon on the People Finder portlet to open the People Finder Configuration, then click the "Directory connection and other essential settings" link to complete the configuration basics.

Configuration Basics lets you connect the People Finder portlet to the LDAP directory by selecting a directory connection (that is, an XML configuration file); to manage the directory connection (import, export, and validate), use the Directory Connector application discussed earlier in this article.

In this section, you can specify a URL to a Web application that allows you to update records in your LDAP directory. That link appears on all Person Records to enable users to update their records in the directory.

Lastly, in Configuration Basics, you can choose which fields from the directory connection you want People Finder to display. A table lists all the available fields that you can choose from. Select the Include checkbox beside the field that you want to display, then select the display format:

Format	Description
String	Displays a text string
Person link	Displays a link to the Person Record
Email address	Displays a mailto link
Web page link	Displays a link to a Web page
Other person link	Displays a link to another Person Record, such as a person's manager

Shared Elements
The Shared Elements section contains two parts: Business Card fields and Sections in Person Record and Advanced Search. The Business Card fields let you determine which fields appear in the Business Card area of the Person Record. You can add, remove, and rearrange fields. You can also include photos of the person in the Business Card.

The Sections in Person Record and Advanced Search lets you add sections to both the Person Records and the Advanced Search form. Default sections for both the Person Record and Advanced Search are Contact Information, Current Job, and Background. You can add, remove, or rearrange sections. In the Person Record and Advanced Search sections that follow, you can change the fields that appear in each section.

Person Record
The Person Record section contains two parts: Person Record fields and Organization View fields. The Person Record lists a number of fields containing contact information, including common name, display name, email address, and so on. Using the People Finder Configuration, you can add, remove, and rearrange fields that appear in the Person Record. First, choose the section in which you want to add, remove, or rearrange fields. To add a field, select the field name from the list of fields, then click Add. To remove a field, select it, then click X to remove it from the Person Record. The People Finder portlet no longer displays that field after you remove it, but you can add the field again later. To rearrange fields in the Person Record, use the up and down arrows for each field name.

The Organization View shows the organizational hierarchy that the person belongs to. In Organization View fields, you can enable or display the Organization View from the People Finder portlet. By default, the Organization View is enabled and shows the common name, office phone number, employee title, and organizational unit. You can add, remove, and rearrange the fields in the Organization View.

Advanced Search
The Advanced Search section also contains two parts: Queries for search and Fields for results. Queries for search lets you add, remove, and rearrange the fields that users can search on the Advanced Search form. The Advanced Search form is divided into sections—Contact Info, Current Job, and Background—so you can customize each section of the form.

Like the Queries for search, Fields for results lets you add, remove, and rearrange fields on the Advanced Search results form. Note that the Advanced Search results form shows far fewer fields than the Advanced Search form.

Quick Search
Quick Search is the simple search field on the People Finder portlet. It lets you select contact information to look for from a drop-down list. Like the Advanced Search section, the Quick Search section contains two parts: Queries for search and Fields for results. Both let you customize Quick Search the same way you would customize the Advanced Search—but with fewer fields. By default, the Quick Search provides the following searches:

Name
User ID
Email address
Office phone number
Department
Employee job title

The Name search uses a byName query which is coded to use a special algorithm that allows the Quick Search to use different filters. When you open the XML configuration file, you see that the byName query appears in the exposed custom queries section:

<exposedCustomQueries>

<description>Query to search for different combinations of first, last and nickname</description>

<customRenderExtension>com.lotus.ap.ds.custom.ldap.LDAPRenderExtensionByName

</customRenderExtension>

<mappedAttribute>FirstName</mappedAttribute>

</queryAttribute>

<mappedAttribute>LastName</mappedAttribute>

</queryAttribute>

<mappedAttribute>NickName</mappedAttribute>

</queryAttribute>

</queryAttributes>

</customQuery>

</exposedCustomQueries>

The <customRenderExtension> element specifies the special algorithm. Different filters are needed to accommodate the different variations in search queries, for instance, typing a first and last name versus typing only a last name. The byName query searches the surname, given name, and common name fields. When you include a comma in the search query—for instance, smith, john—then the word before the comma is treated as a surname, and People Finder searches for an exact match. If you do not use a comma, then People Finder searches all three fields.

Tip: Do not use the wildcard asterisk (*) in a search. People Finder automatically appends the wildcard to a search, so if you add the wildcard, the search query includes two asterisks (**) which some LDAP servers do not support (Domino being an exception). People Finder does not support wildcard (*) only searches.

Conclusion
This article should have provided you with an overview of the People Finder portlet configuration options. It should also have explained how to use the Directory Connector to connect the People Finder portlet to your LDAP directory server. Your organization will likely find the People Finder portlet as valuable an asset as we at IBM find the BluePages application, so put your options to good use to make the most of the People Finder portlet.

ABOUT THE AUTHOR
Sam Alexander works for the IBM Lotus Product Introduction Engineering team. As a tools developer, he helps develop software tools and recommends methodology used in performance testing, data collection, and data analysis. Working with the Discovery Server Performance Team, he recently developed performance tests and analyzed results for the Lotus Discovery Server 2.0 and 2.0.1 search functionality. Outside of work, Sam is earning a Masters Degree in Computer Science from Boston University's Metropolitan College. Originally from North Carolina, Sam enjoys exploring New England and running local 5K and 10K road races.