Introduction

I've used the lsxldap tool for quite some time now to do e-mail look-ups in web applications. It isn't a very pretty way of accomplishing LDAP lookups but it does work and it works rather well I might add. The company I work for isn't a big Notes / Domino shop, as a matter of fact the powers that be don't want Notes / Domino in their company as it is viewed as Legacy technology. Quite frankly I just think that they don't understand what it is and what it isn't. But, since they aren't that big on Notes / Domino our directory servers are not Notes driven and the need to provide e-mail addresses and other people type information in Notes / Domino applications is still required.

Now, the old fashioned way of doing this was to import the meta-directory into a Notes Address Book and use the information that way. While this is still a relevant means of accomplishing this it is slow and process intensive and in my experience results in a very large import database over time. Not to mention the fact that a new employee will not show up in Domino until the next import. With the lsxldap tool you can do lookups on the fly and save having to create an import database, import agent, import text file and setup the ftp process to get the text file to your Domino server.

Now above I stated that I use lsxldap for web lookups. The truth of the matter is it also works from the Notes client but the Notes client already has an LDAP tool which is fairly simple to setup for looking up e-mail addresses on an LDAP server, so I think it would be a duplication of effort to use this on a Notes client, unless of course you want to pull specific information which lsxldap is perfectly capable of doing. The biggest drawback is that lsxldap.dll will need to be on every user's machine in order for it to work. Depending on how big or small the user base will be this could prove quite a task. I guess the best way around this would be to include it in your Lotus Notes client install package if you want to use this tool on the Notes client.

So, why don't we set it up and get this working for us....

Conventions used in this document

This sequence of characters <--- represents a comment

Words in bold italics are things that you will have to modify to match your setup / system

Words in blue are LotusScript

Words in light blue are Lotus Formula language

Words in Italics are command line commands

NOTE: For the sake of brevity the examples given in this How-To will be hard coded. How you get the pertinent information is up to you. My personal favorite is via a configuration document

Doing the configuration

In order to set all this up you will need to put the lsxldap.dll file in your Domino Server's program directory. You will probably have to get your administrator to do this for you. You don't need to register the dll or anything fancy, it just has to be in the path somewhere. Now we'll write an agent to do the search and populate a field on a form for us. So, go ahead and open the Lotus Notes Designer.

lsxldap

lsxldap has several classes, methods and properties. These are all documented in the download from the sandbox. The documentation is pretty good but it seems that a lot is assumed about your knowledge of directory servers. In my case, I didn't / don't know much about directory servers, but, I can read and figure out what I need to know. Everything I've tried with this tool has worked as expected. Sometimes seems the tool can be picky, but I'm only a mediocre developer so it may have been me fat fingering something.

The Forms

Now, to get all this working we'll have to create 2 forms. The first form will only contain 1 field. This is the field we will type the value we're looking for. Now what you type here should be something that will return 1 result, a unique identifier for the person such as a network id or something to that effect. Now of course you can take this tutorial farther and add your own code to handle multiple results, but that's up to you.

Create a new form and add 1 Editable field. I'll call the field ID.

In the form's WebQuerySave event enter the following formula @Command([ToolsRunMacro];"WebSave");"")

Create a Submit button and in the onClick event add submit()

Save and Close the form and name it Form1

Create another new form (you can use an existing form but for the purpose of this tutorial I'm using a blank database with 2 forms and an agent)

Create a computed field on the form. I will call this field ID2 and the default value will be @Middle(Query_String_Decoded;"id=";":") as this will be the unique value which we lookup. It is very important that we try and use a unique value if we only want 1 return

Create a second computed field on the form. I will call this field EmailAdd and this will contain the e-mail address which we are looking up. The default value should be @Middle(Query_String_Decoded;"email=";":")

Create a third computed field on the form. This will HAVE to be called Query_String_Decoded and have a default value of Query_String_Decoded

Save and Close the form and name it Form2

The Agent

This agent will run when the user inputs their network ID and clicks the submit button on Form1. The agent will take that ID and do a lookup in the LDAP directory and return a result or return no result. So, lets get started coding to make this work...

Create a new agent and name it WebSave

Choose LotusScript as the type of code

Make the agent run On Schedule Never

Target = All documents in database

Now, for the fun part...

Sub Initialize
dim ses As New NotesSession
dim db as NotesDatabase
dim iddoc as NotesDocument
dim webdoc as NotesDocument
dim ldapses as LDAPSession
dim ldapser as LDAPSearch
dim ldapres as LDAPResultSet
dim id as String
dim num as Integer
dim query as String
dim URL as String
set db = ses.CurrentDatabase
set iddoc = ses.DocumentContext
id = iddoc.id(0)

set ldapses = New LDAPSession
set ldapser = New LDAPSearch
set ldapres = New LDAPResultSet
ldapses.dn = "" <-- This is the username to use to connect if required. We will be using anonymous here
ldapses.Password = "" <-- This is the password for the above user name
ldapses.Host = "ldapserver.host.name" <-- This is the hostname of the ldap server you want to connect to
status = ldapses.Connect

If status Then
Set ldapser.Session = ldapses
Set ldapser.ResultSet = ldapres
query = "(AnyAttribute=" + id + ")" <-- This is the search string or query string. You can make this as simple or complex as you like. The AnyAttribute will vary from place to place. You will need to contact the administrator of the LDAP Directory to figure out what this should be as we're wanting to search all attributes in case what you're searching for is hidden for whatever reason.
ldapser.Filter = query
ldapSer.scope = LDAP_SCOPE_SUBTREE <-- I believe this is saying to search a subtree of the directory. Not sure here, maybe someone can clue me in here.
ldapser.Execute
num = ldapres.Count
If num <> 0 Then
Set ldapEntry = ldapres.GetFirstEntry
emailadd = ldapEntry.getValueString("mail") <-- The mail attribute may be different in your situation. Again, contact your LDAP administrator to find out what this attribute is.
URL = "http://yourdomain.com/" + db.FilePath + "/Form2?OpenForm&id=" + id + ":email=" + emailadd + ":"
Print |[| + URL + |]|
Else
Print "Not Found" <-- This can be the url of another page or whatever you prefer. I did it this way for brevity.
End If
Else
Print "Not Connected to LDAP Server"
End If

ldapses.Disconnect <-- If you don't do this and you run a loop to do multiple lookups then your LDAP Directory administrator will get upset because you will use up all the server sessions " width="19" height="19">
End Sub

Giving it a test

OK, so now we need to give this a try. So, open up your browser and type in the URL:

http://yourdomain.com/dbname.nsf/Form1?OpenForm

Type in the ID or other Unique identifier for someone you know is in the LDAP Directory

Click Submit

Now you should get a page with the Query_String_Decoded at the top, the ID you searched for next and then the resulting e-mail address

Now, I know that this isn't very pretty but it gives you a starting point of just how to do a basic lookup. You can pull as much information as your LDAP Administrator will allow from the LDAPEntry just as you would a ViewEntry object. If no results are displayed then verify that the AnyAttribute and hostname are correct. Like I said, you will probably need to contact your LDAP Administrator for some of the information that you will need to make this work properly.

The ldapsearch.exe Tool

There is also another command line tool available that gets installed with Lotus Notes. It's called ldapsearch.exe and can be a great tool for helping you find out more information about what fields are what in the LDAP Directory. Now, this tool will not show you fields which your LDAP Administrator has hidden, but, you will be able to see all the publicly available fields / attributes. You will have to open the command prompt and change dir (cd) to your Notes Program directory. So, the syntax goes something like this...

ldapsearch.exe -h ldapserver.host.name AnyAttribute=IDtoSearchFor mail

Now, this should return the E-Mail address of whoever's ID you searched for considering that the attribute name for the E-Mail address is mail. You can also display all the public attribute names like so...

ldapsearch.exe -A -h ldapserver.host.name AnyAttribute=IDtoSearchFor

But the basic syntax for this tool is as follows:

ldapsearch.exe [Options] Filter [Attributes]

And here is the help that is displayed by just typing ldapsearch at the command line with no options:

usage: ldapsearch [Options] Filter [Attributes]
where:
Filter RFC-2252 compliant LDAP search filter (filter length greater than 255 should be used in a file with -f option)
Attributes whitespace-separated list of attributes to retrieve (if no attribute list is given, all are retrieved)

Options which affect the protocol request:
-a deref Alias dereferencing [never : always : search : find]
-A retrieve attribute names only
-b basedn base dn for search [""] (if the environment variable LDAP_BASEDN is set, -b flag is not required)
-D binddn bind dn for simple authentication [NULL i.e. anonymous]
-h host ldap server [server.acme.com]
-l timeout time limit (in seconds) for search [15]
-p port port on ldap server [389]
-s scope Scope of search [subtree : onelevel : base]
-z size size limit (in entries) for search [0=unlimited]
-w passwd bind passwd for simple authentication [NULL]
If an option above is not specified then the value in [] is the default.
If more than one value (: separated) is specified then these are the only legal values (1st value is the default if option not specified).

Options which affect the tool behavior:
-B do not suppress printing of non-ASCII values
-f file perform sequence of searches listed in `file' (may use with filter pattern (ex. "cn=%s") or without)
-F sep print `sep' instead of `=' between attribute names and values
-L print entries in LDIF format (-B is implied)
-n show what would be done but don't actually search
-x server side sort - must be used with [-S attr] option (do not use with referrals)
-R do not automatically follow referrals
-M manage referral objects as normal entries
-S attr sort the results by attribute `attr'
-t write values to files in TMP directory
-u include User Friendly entry names in the output
-v run in verbose mode (diagnostics to standard output)

Release 6.0.2CF1|June 9, 2003

Conclusion

I hope you find this article useful and I know it's really on the simple side of this tool. However, when you download lsxldap from the Sandbox it comes with a database which contains lsxldap.dll and excellent documentation (well, ok documentation ). This in my opinion is a very powerful tool and works as advertised it would work. So, give it a try and hopefully you'll be pleased with the outcome. You can also be as simple as what I have above or as complex as you care to make it. It's really totally up to you, but hopefully I've given you an idea of how to use the tool and set your imagination in motion.

The ldapsearch.exe tool is also very useful for finding out information about the fields / attributes on your directory server. As for using ldapsearch.exe in a production type situation, the tool is kind of slow and would be hard to implement from a development capacity (ok, hard for ME to implement from a development capacity " width="19" height="19">), but useful none-the-less.

I have also included a sample database with the 2 forms and the agent documented above and you can download it here. If you have any questions or think I missed something or wrongly represented something in this article please feel free to contact me.

So, until next time...... Later
Keith

©2004 Keith Strickland and www.keithstric.com