Displaying Sametime user names in the Microsoft Outlook toolbar

The Sametime® Integrator for Microsoft Outlook (or “Outlook toolbar”) works by asking Sametime to process an identifier phrase – in the case of Microsoft Outlook, the phrase is an email address. If the server is not configured to resolve the email "phrases" found by the toolbar, the Target Contact button is not updated to show the Sametime display name and status, but instead continues to show an email address, such as “jsmith@example.com” or “JSMITH” (a CN portion of an X.400 address).

About this task

There will always be emails from external parties that will remain unresolved, but you can follow these steps to resolve the email addresses of Sametime users.

Procedure

Enable logging in the Sametime client.
As any new email address is encountered, an XML message is sent from the Outlook toolbar to the Sametime client for lookup processing. These messages can be echoed into the client logs. The configuration information for a user is stored in a workspace under the user's Documents and Settings folder, under the path Documents and Settings\User\Application Data\Lotus\Sametime\.config. The rcpinstall.properties file located here is processed on each launch of the client.

Open this and add the following line to the end of the file:
```
com.ibm.collaboration.realtime.brokerbridge.level=FINE
```
On all subsequent launches, the XML traffic between the Sametime client and the Office Integration features will be logged to the trace-log-N.xml files in the Application Data\Lotus\Sametime\logs folder.

A few tips will simplify using these logs:
- Focus the troubleshooting effort on just one Office application – so avoid opening other Office applications or SharePoint pages, because their message traffic will overlap the Outlook messages and make the logs larger.
- The Sametime client usually needs to be exited to complete the writing of the logs – the easiest approach is to start Sametime, click a few problem emails, then exit the client and examine the logs.
- The logs are designed to be opened in a browser from the Application Data\Lotus\Sametime\logs folder, which contains formatting files to create tables of output.
Find the resolution request.
Once the trace log is opened, use the browser's function to search for text in the page and search for the phrase “liveNameResolve”. This XML message is the type used by Outlook toolbar to request resolutions – because email addresses map uniquely to one person, the toolbar is using the lookup service which returns only unique matches. Once the table row containing a liveNameResolve is found, the target phrase is located in the lookupName section – this in turn is an array of one or more phrases, in stringArray\data nodes. As a concrete example, an email within the STOIDEV enterprise from user John Doe might cause a liveNameResolve like this one:
```
<?xml version="1.0" encoding="utf-8" ?>
 <messageSet version="1.0" signed="false">
    <liveNameResolve typeVersion="1.0">
       <lookupNames valueType="stringArray"><stringArray length="1">
        <data><!<CDATA<CN=John Doe,CN=Users,DC=stoidev,DC=com>>></data>
  </stringArray> </lookupNames></liveNameResolve><signature /> </messageSet>
```
This example has been formatted for this page – it may appear as a single line in the logs. So the email address phrase here is CN=John Doe,CN=Users,DC=stoidev,DC=com.

Note that in this example (from a real Exchange test set-up) this particular format of the email address is NOT ordinarily displayed to the Outlook user – instead, the user sees “John Doe” or “jdoe@stoidev.com” displayed in Outlook documents and dialogs.
Check the phrase.
A quick check for resolution results can be accomplished by starting the Sametime client and clicking Add Contact. Then, paste the phrase from the liveNameRequest (CN=John Doe,CN=Users,DC=stoidev,DC=com in this example) into the User name field of the "New Contact" dialog box, and click Lookup. If the phrase returns a unique result, then the toolbar should likewise get that result and operate fully for that target contact. If there are no results, or if there are multiple results, then the toolbar resolution will not be able to display a Sametime user for that address.
Adjust the server configuration.
Both the Sametime client and the Outlook toolbar (working within the Sametime client), rely on the Sametime server to associate a particular phrase with a user. No other communications to directories are in use – if the Sametime server cannot establish the association, the Outlook toolbar can only assume that none exists. However, the Sametime server has great flexibility and can be directed to use any of the directory fields at its disposal when doing this processing.
The field called "Search filter for resolving person names" in the "Searching" settings of the LDAP Directory configuration for the Sametime Community Server dictates the query that is used. Notice that "mail=%s" is a recommended setting, and will be successful when the ID phrase is the SMTP email address "ajones@example.com". For cases like the previous example, the default settings for many Exchange deployments will have this address phrase, in its entirety, within an attribute called “legacyExchangeDN” – so a query term “(legacyExchangeDN=%s)” would typically be added as an addition to the “(mail=%s)” and others present in the filter string. Other cases could require inspecting available directory attributes to find a suitable match; for example:
```
(&(objectclass=organizationalPerson)(|(mail=%s*)(cn=%s*)(legacyExchangeDN=%s)
(userPrincipalName=%s*)))
```
In addition, to ensure that the Microsoft Exchange contacts are correctly resolved and authenticated, add the query term (legacyExchangeDN=%s) to the Search filter to use when resolving a user name to a distinguished name field in the Searching settings of the LDAP directory configuration for the Sametime Community Server. For example:
```
(&(objectclass=organizationalPerson)(|(cn=%s)(givenname=%s)(sn=%s)(mail=%s)
(legacyExchangeDN=%s))) 
```
One final detail is that the Sametime server, by default, will skip over attribute values that are in LDAP canonical format as a single field, but it offers an override – this override would be required in the legacyExchangeDN case, for example. To establish the override behavior, edit the Sametime server's sametime.ini configuration file and add this line:
```
ST_DB_LDAP_ALLOW_SEARCH_ON_DN=1
```
to the section labeled [Directory]. If there is no such section already, create one by appending the two lines at the end of the sametime.ini file:
```
[Directory]
ST_DB_LDAP_ALLOW_SEARCH_ON_DN=1
```