There are two new features available in Lotus Instant Messaging (Sametime) 6.5.1 that enhance the end user experience and that make the running of Lotus Instant Messaging less intrusive on corporate resources: LDAP directory search configuration (or customized LDAP search filter) and controlling the format of user names returned. This article describes these features in detail and provides comparisons with what is available in Sametime 3.x. It also shows you how to implement these features with code examples. Once you know the benefits of these enhancements, we believe that you will want to implement them after you upgrade to Lotus Instant Messaging 6.5.1.

This article assumes that you are an experienced Lotus Instant Messaging administrator with Java programming experience. No toolkits are required to customize the LDAP search filter or to change user name formats. This article uses Java 1.3 to create the Java classes.

The custom LDAP search filter in Lotus Instant Messaging 6.5.1

Based on knowledge of your LDAP directory structure, you now have the ability to dynamically determine how LDAP lookups can be formatted. This ability also extends to determining which search patterns are acceptable (for instance, wildcards) and which attributes may be searched with wildcards.

Administrators can write Java classes to customize the logic by which Lotus Instant Messaging conducts LDAP directory searches. These Java classes can control the manner in which Lotus Instant Messaging searches the LDAP directory for user and group names. See the Lotus Instant Messaging and Web Conferencing 6.5.1 Administrator's Guide section, "Using a Java class to customize LDAP directory searches" for more information. The same Java source code can also have classes that control the formatting of user names returned from LDAP searches as described in the Administrator's Guide and later in this article.

Benefits of the custom search filter

If you have never used a custom search filter before, here's what you can gain by implementing one:

• Use of wildcard characters in the client login name can be either prohibited or allowed under certain situations to make the product more secure.
• Construct simpler search formulas for full Notes names or full Internet mail addresses to reduce search complexity on the LDAP servers. The result is less overhead on the LDAP servers which translates into quicker search results and improved performance on the LDAP server because of the less complex search string.
• With the inclusion of presence awareness in Notes/Domino 6.5.1, Notes names can be processed in either canonical or abbreviated format without requiring client changes even if the directory contains only the canonical form of Notes names.
• More flexibility in the resolve search formula (such as allowing common name or surname) can be added to the LDAP search formula to help users find other users during the People-Add process for adding users to a buddy list. This is done without adding extra overhead on the LDAP servers for the lookup of full Notes names or full Internet mail addresses as passed by the Notes/Domino 6.5.1 awareness code.

Implementation and example

To implement the Custom Search Filter, specify a Java method instead of a static search filter in your Lotus Instant Messaging configuration. This method must exist in the Lotus Instant Messaging program directory. See the Lotus Instant Messaging and Web Conferencing 6.5.1 Administrator's Guide for more information.

For example, to specify a search filter for resolving person names, Lotus Instant Messaging calls the Java method peopleResolveFilter () in class StLdapCustomized for each resolve request:

StLdapCustomized.peopleResolveFilter ()

It passes this method the requested user initiated search string (for example, tsmith@company.com) with the routine returning the correct LDAP search string:

"(&(objectclass=person)(mail= tsmith@company.com))"

Lotus Instant Messaging then uses this LDAP search string to query LDAP to determine the person's existence.

LDAP directory structure

Now, let's examine a sample LDAP directory structure that we use as the basis for comparing both search methods.

We compare search strings generated using the static search filter and the custom search filter. The search attribute chosen is the one used for resolving person names. The applications that have presence awareness need these LDAP attributes: cn, sn, mail, dominoid. Notice the complexity of the static search filter and the additional overhead this string generates on the LDAP server.

PersonResolveFilter="(&(objectclass=Person)(|(cn=%s*)(sn=%s*)(mail=%s*)(dominoid=%s)))"

The following custom search filter statement tells Lotus Instant Messaging to load the Java method userSearchFilter() in class StLdapCustomizedAttributes to handle the LDAP resolve request.

PersonResolveFilter="StLdapCustomizedAttributes.userSearchFilter()"

When an LDAP resolve request comes in, Lotus Instant Messaging calls this method with the requested name, and the method returns the search filter.

Now, let's see the actual search string used. In this example, a user tries to add Tom Smith to his buddy list, using the specified search string: tsmith@co. The code uses the following static search filter to search for Tom Smith:

PersonResolveFilter="(&(objectclass=Person)(|(cn=tsmith@co*) (sn=tsmith@co*)(mail= tsmith@co*)(dominoid=tsmith@co)))"

Because a static filter must specify every LDAP attribute needed to help users find their contacts and because it is unable to dynamically determine which attributes are needed for a specific request, all specified attributes are always used in the search string. Applications, such as Notes 6.5.1 that have presence awareness, tend to use a limited set of values (such as dominoid or mail) in a resolve request, but static search filters cannot take advantage of that.

If you implemented the custom search filter, you use the following custom search filter to search for Tom Smith:

PersonResolveFilter="(&(objectclass=Person)(mail=tsmith@co*))"

A custom filter has the ability to dynamically determine the attributes needed so that only the attributes that could have that value in a directory record are used in the string. In the search case above, it is known that the "@" symbol can only occur in the mail field in the LDAP directory, so only that field needs to be searched.

Example of a custom search filter code

The example custom filter routine is used for authentication. It requires that full values be entered and does not allow any wildcards in the input nor does it append the asterisk. The filter supports entry of the Internet mail address or the Notes ID in either canonical or abbreviated format.

public static String userSearchFilter(String parm1) {
	String temp; int atsign;
//Prevent users from adding wildcards "*" & "?"
	if (parm1.indexOf('*') != -1) return null;
	if (parm1.indexOf('?') != -1) return null;

// Check to see if search string looks like a mail address 
if ((atsign=parm1.indexOf("@"))>=0 )  
return ("(&(objectclass=person)(mail=" + parm1 + "))");

// Check to see if the search string is a canonicalized Notes ID
	temp = parm1.toLowerCase();
	if (temp.startsWith("cn=")) 
return("(&(objectclass=person)(dominoid=" + parm1 + "))");

// Check to see if the search string is an abbreviated Notes ID
if (temp.indexOf("/")!=-1) 
return("(&(objectclass=person)(dominoid=" + canonicalizeFullName(parm1) + "))");
// The canonicalizeFullName method is just Java code to convert abbreviated 
// Notes IDs to canonical form and would be needed for this sample to work

	// Not any acceptable form so return null
	return null;

}

Here are a few things to note about the previous code snippet:

• If you try to log in with tom smith or t_smith* or t?mit?@company.com, the custom search filter returns the null string and log in fails.
• If you try to log in with tsmith@company.com, the custom search filter generates the string "(&(objectclass=person)(mail= tsmith@company.com))" and log in succeeds if the password is correct.
• If you try to log in with tom smith/sales/company, the custom search filter generates the string "(&(objectclass=person)(dominoid=CN=tom smith/OU=sales/O=company))" and log in succeeds if the password is correct.

Back to top

Controlling the format of user names returned

Along with the custom search filter, we think it's appropriate to discuss another feature available in Lotus Instant Messaging 6.5.1, which controls the format for user names returned from LDAP. The user names returned are what appear on users' buddy lists if users do not specify nicknames and in the selection list if a People-Add search finds multiple possible entries in the directory. As the Lotus Instant Messaging administrator, you have the ability to influence how these names appear and are not limited to using only a single field value from the LDAP directory. See the Lotus Instant Messaging and Web Conferencing 6.5.1 Administrator's Guide for more information. This feature was added to Sametime 3.1, but was not documented in the Sametime 3.1 Administrator's Guide, so its availability is not well known.

Implementation

Referencing our LDAP directory structure from above, let's assume a Lotus Instant Messaging server is setup like this:

As with the custom search filter, Lotus Instant Messaging calls the Java method StLdapCustomizedAttributes.DisplayName, passing it the user's mail and dominoid. The Java method can change the format or contents of either string and pass back any combination to be used by the client. For example, the canonical dominoid CN=Tom Smith/OU=Sales/O=Company can become Tom Smith/Sales/Company.

Example

Here is what shows up on a user's buddy list using the setting above:

Using Sametime 3.x LDAP setting: tsmith@company.com

Using Lotus Instant Messaging 6.5.1 LDAP setting: tsmith@company.com - Tom Smith/Sales/Company

As you can see, the second example gives a better identification of the user as it shows both the mail and Notes name of the user which probably makes it unnecessary for a nickname to be used. It also is much nicer to have the abbreviated Notes name instead of the canonical name. Because there is no single field in the LDAP directory with the desired value, using custom Java code is the only way to achieve the desired result. The Java code to do this is:

public static String DisplayName(String mail, String dominoid) {
	return (mail + " - " + abbreviate(dominoid));
// the method abbreviate is just Java code to abbreviate a canonical Notes name
// it is not shown here, but is needed to make the example work 
}

Back to top

Making changes to the server

Now that you have your Java code, compile it, and then copy the compiled code to the Java subdirectory of the program directory for a Domino-based Lotus Instant Messaging server or to the program directory for a stand-alone Lotus Instant Messaging server. Update the Java parameters in your Sametime.ini file so that the ST_JAVA_CLASS_PATH setting points to the copied file, and then add the ST_JAVA_JVM_PATH setting to point to the jvm to be used. Lastly, in the Lotus Instant Messaging Administration Tool, enter the Java class and method names used. For details on how to perform this procedure, refer to the Lotus Instant Messaging and Web Conferencing Administrator's Guide.

Back to top

Conclusion

By using the custom search filter and by controlling the user name format, you can improve the user experience for your users. Not only is searching for a name in an LDAP directory easier for a user and more efficient for the LDAP directory server with a custom filter, but identifying users with an abbreviated name format makes buddy lists simpler and easier to read. This article shows you only two of the new features available in Lotus Instant Messaging and Web Conferencing 6.5.1. For more new features, see the Lotus Instant Messaging and Web Conferencing 6.5.1 Release Notes.

Resources

• Lotus Instant Messaging and Web Conferencing documentation
  
  
• Lotus Instant Messaging and Web Conferencing page on developerWorks: Lotus
  
  

About the authors

Comments

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• The custom LDAP search filter in Lotus Instant Messaging 6.5.1
• Controlling the format of user names returned
• Making changes to the server
• Conclusion
• Resources
• About the authors
• Comments

Next steps from IBM

• Try: Lotus Sametime
• Demo: Lotus Notes 8 composite applications
• Webcast: A Smart Approach to Core Banking Renovation in a Tough Economic Climate
• Briefing: Smarter collaboration with IBM Lotus solutions
• Buy: Lotus Sametime

My developerWorks community

Dig deeper into Lotus on developerWorks

Calling all developers

Download no charge Lotus Domino Designer

Special offers