ShowTable of Contents
This article explains the custom adapter feature for IBM® Directory Search portlet, a.k.a, People Picker, showing how to write it and register it with IBM WebSphere® Portal. It's intended for anyone who uses Directory Search portlet with WebSphere Portal Server and is interested in a custom (user-defined) search for their application.
Understanding Directory Search portlet
Directory Search portlet is a component that lets you look up the names of people and groups in a directory, after which you can choose a single name or all names from the searched people and groups list for your task.
You can use this component for every task for which user selection is required. The following are a few examples in WebSphere Portal where this component comes into play:
- Address mail: Select names for ‘To’,’cc’ and ‘bcc’ fields
- Invite people to a meeting
- Add a name to your address book
- Add a name to your instant contacts
- Assign a role to document
Obviously, each of these tasks requires a person or group for its completion. By default, all these tasks look up in the default Portal directory, unless each task is configured with a different directory.
However, you may want to search people or groups in different directories for different tasks. For example, you may want to search the Domino directory for “Mail address” and in the Tivoli directory for “Invite people to a meeting”. In such a situation, you will not be able to perform a search until this component is configured with both directories.
To look up in different directories, the requirements are as follows:
- Each directory must be visible to the IBM Directory Search portlet.
- Each task must provide the value for the directory in which the search is made, to populate the “Search in” drop-down list in the IBM Directory Search portlet.
A directory can either be a user-defined repository or a Directory server like IBM Tivoli® Directory Server (ITDS), IBM Lotus® Domino®, or Microsoft® Active Directory server.
Figure 1 shows the two-tier architecture of the custom search adapter.
Figure 1. Two-tier architecture of custom search adapter
This portlet is different from other user/group search components in that:
- it's used as a part of a task (like sending an email requires recipients, sending a document link to other people with access to the same document, etc.)
- it searches both users and groups
Directory Search portlet custom adapter
As mentioned above, it's possible to allow the Directory Search portlet to execute a search in a user-defined repository other than the default repository of the WebSphere Portal Server.
Custom search provides the option to Portal users to write their own search adapter in order to search a set of defined users and groups. By doing this, users can have their own adapter that displays in the “Search in” drop-down list in the Directory Search portlet (see figure 2).
Figure 2. Custom adapter key (‘CUSTADAPTER’) in drop-down list
Writing a custom adapter
There are two interfaces that must be implemented in order to write a custom adapter:
Listing 1 shows the PeopleView interface.
Listing 1. PeopleView interface
Listing 2 shows the PeopleViewFactory interface.
Listing 2. PeopleViewFactory interface
Register custom adapter with WebSphere Portal
The custom adapter will not work or will not display in the Directory Search portlet until we register it with WebSphere Portal. To do this, we must modify the following two property files:
This file enables the Directory Search portlet to know details about your adapter, for example,
- Id. Unique identifier for custom adapter.
- Bundle name. Contains key-value pair for custom adapter.
- Display name key. Name of custom adapter
- Maximum search results. Limit for search result (the number of entries that display in the search result)
- Minimum characters required for search. Length of “search for” field (minimum number of characters in name for searching)
- Policy required. The available policies that can be required for the adapter to be available are:
This property file also contains entries for “display attributes” in the Directory Search portlet.
The following entries must be added to the pickersettings.properties file:
people.view.1=CUSTADAPTER.1,com.ibm.sample.bundle,displayname.key,serv.locator.key,100(max search results),2(min chars to type)
Display attributes list:
cn. Common Name of searched user/group.
ibm-primaryEmail. Email Id of searched user/group.
Listing 3 shows an example of pickersettings.properties.
Listing 3. Example of modification to pickersettings.properties
This file enables Directory Search portlet to look up your adapter factory.
Invoke custom adapter from application
To invoke or to display the custom adapter in the Directory Search portlet, we must include a custom adapter name (say CUSTADAPTER) in the “dirs” url parameter of WebSphere Portal's “urlGeneration” tag. The invocation code will look like that shown in listing 4.
Listing 4. Code for WebSphere Portal urlGeneration tag
After custom adapter (CUSTADAPTER) is added in dirs, it will display in the “Search in” drop-down list as shown in figure 2.
Figure 2. Web Page Dialog window
This article described how to use the Directory Search portlet for user-defined searches, using the customized search adapter in WebSphere Portal Server. You learned the steps for writing, registering, and integrating the custom search adapter.
WebSphere Portal product documentation:
IBM Support Technote #1419925, “How to customize Directory Search (People Picker) portlet queries:”
IBM Support Technote #1379931,”Customizing the People Finder and Directory Search ("People Picker") query:”
About the author
is Staff Software Engineer based at IBM's Delhi, NCR, India facility. He works on WebSphere Portal development and on customer engagements, and is currently the technical lead for People Components for WebSphere Portal. Deepak holds a Bachelor's degree in Computer Science and Engineering from the Indraprastha University, India. You can reach him at Deepak.Gupta@in.ibm.com