Corporate lookup settings

Many settings can be modified for the corporate look up feature.

  • The minimum number of characters typed before a lookup is executed.
  • The maximum number of results returned to the device.
  • Which server the lookup is executed against.
  • Which directories are searched.
  • Enforcing access control lists.
  • The search depth performed by the look up function.
  • What fields are retrieved from the directory and how they are sent to the device.
  • What fields are used for duplicate resolution.
  • What mail address fields are encoded for Apple Devices.
Note: A server restart is typically required after changing any corporate look up setting.

All settings below can be updated by changing and/or adding a property in the notes.ini for the server.

Configuring how many characters are typed before the query is performed

Apple and Android devices will search as you type. To improve performance, a default of three characters must be typed before the actual look up initiates. You can configure this value by setting NTS_NAME_LOOKUP_MIN_LENGTH.

Configuring the maximum number of results to return to the client

By default the maximum number of results sent to the device is 30, which ensures that the number of records sent to the device is small. This value can be changed, but it is recommended you keep it relatively small to prevent device performance issues. The value can be configured by modifying the NTS_NAME_LOOKUP_MAX_RECORDS property.
Note: Exchange ActiveSync devices specify a maximum number of look up results for performance reasons. This maximum setting can not be over ridden. For Apple devices, the maximum requested is 51. For Windows Phone, Windows Tablet, and BlackBerry devices the maximum requested is 100, but Windows Phone devices only show 50. For all devices, there is no way to ask for the remaining results, so you must refine the search further if you need a known result that is not in the set displayed on the device.

Configuring which server to perform the lookup against

By default the lookup is performed against the user's mail server. This is done to reduce configuration needed on the HCL Traveler server and provide more consistent results with a Notes® Client. The behavior can be changed to perform the lookup operation against the HCL Traveler server instead. To have lookups performed against the HCL Traveler server, set NTS_TRAVELER_AS_LOOKUP_SERVER=true.

Which directories are searched

The look up itself is a Domino® server operation. The Domino server will search the local address book and any directories specified by Directory Assistance. For example if using a corporate LDAP you will need to setup Directory Assistance such that the Domino server can look up entries in the LDAP server. In general, the user's mail server should already have appropriate configuration for handling search requests from a Notes Client. See the Domino documentation on Directory Assistance for more information.

Enforcing access control for lookup

By default, the corporate lookup function does not enforce ACL restrictions inside a directory for the user performing the look up. To enforce ACL restrictions, perform the following procedure:
  1. Ensure all HCL Traveler servers have set NTS_LOOKUP_ENFORCE_ACL=1 in the notes.ini. A setting of 0 is the default.
  2. Ensure the HCL Traveler server has read access in the ACL of the primary directory of the mail server, as well as any secondary address books that may need to be searched.

    Do not use the Unspecified type in the ACL. Instead, identify it as a Server (or Server Group when using a group). When using a server group, the group type in the name and address book must be Server group. Do not use mixed groups.

  3. Ensure that the names and address books that need to have restricted access use the Extended ACL. Additionally:
    • It is important that the extended access portion of the ACL be configured to contain the groups that should have access to search the directory.
    • To prevent unauthorized users from viewing data in the directory, confirm that the default and anonymous entries are set to No Access and do not have the Read public documents checkbox selected.

For more information on the extended ACL, see the Domino documentation on using ACL and Extended ACL to control access to directories.

Search depth

The default search depth is an exhaustive search of all directories found. This search depth is the most common, however it can be configured with one of the values shown below.

To change the setting, update the NTS_NAME_LOOKUP_FLAGS attribute.
  • 0 means that the lookup will not match partial names and will stop searching once a match is found.
  • 8 means that the lookup will match partial names, but again will only return the first value found.
  • 32 will not match partial names, but will perform an exhaustive search of all directories including ones specified in directory assistance. It will return all results.
  • 40 (default) will match partial names and perform an exhaustive search of all directories.

Configuring which items should be retrieved from the directory

The default set of items retrieved from the directory are generally sufficient for most environments, but if you are using an LDAP that uses non-standard field names, it may be necessary to configure them specifically. The search uses the order of the fields as the priority when returning results. As a result, the order of the fields should represent the desired sort order as closely as possible. To determine the field names of your LDAP you may need to contact your LDAP administrator or use an LDAP browser application. To change the fields, modify the NTS_NAME_LOOKUP_ITEMS_EXT property. Due to line length limitations in the notes.ini file, the NTS_NAME_LOOKUP_ITEMS_EXT property must be split into segments of less than 256 characters each. For example:
NTS_NAME_LOOKUP_ITEMS_EXT=NTS_ITEMS_1, NTS_ITEMS_2 NTS_ITEMS_1=LastName,FirstName,MiddleInitial,ListName,FullName,Type,$$NoteID,Title,Suffix,OfficeStreetAddress,OfficeCity,OfficeState,OfficeZIP,OfficeCountry NTS_ITEMS_2=StreetAddress,City,State,Zip,country,JobTitle,CompanyName,Department,InternetAddress,CellPhoneNumber,PhoneNumber,OfficePhoneNumber,WebSite
This is the complete default list of fields in sort order. When modifying the list, be careful to maintain the proper sort order for the fields.
LastName,FirstName,MiddleInitial,ListName,FullName,Type,$$NoteID,Title,Suffix,OfficeStreetAddress,OfficeCity,OfficeState,OfficeZIP,OfficeCountry,StreetAddress,City,State,Zip,country,JobTitle,CompanyName,Department,InternetAddress,CellPhoneNumber,PhoneNumber,OfficePhoneNumber,WebSite

Once the fields are retrieved from the directory, you can then change how they get mapped to the device. This differs based on device type. For Apple devices, see Customizing the Exchange ActiveSync XSLT file. For all other devices, see Customizing the VCARD XSLT file.

Duplicate resolution

Often, you will have a particular entry in more than one directory, or even in the same directory with different names. To prevent duplicate results from being sent to the device, you can specify a field or fields that are required to be unique. If the field contains a duplicate entry, then it is ignored and not sent to the device. By default, the fields InternetAddress and $$NoteID are used for duplicate resolution. You can configure which fields to use in the NTS_NAME_LOOKUP_UNIQUEITEMS property. Note that in order for the field to be used for duplicate resolution, it must be returned by the lookup. Therefore any field specified in NTS_NAME_LOOKUP_UNIQUEITEMS must also be specified in NTS_NAME_LOOKUP_ITEMS_EXT, or in the default list if not specified. Otherwise, the item will be ignored for duplicate resolution.

E-mail address fields

Apple devices do not handle Domino style mail addresses well. To improve usability and overcome some functional concerns, all non-standard mail addresses sent to an Apple device are encoded to a format that Apple devices understand (for example, name@yourco.com). By default, corporate lookup is done for the InternetAddress field. To apply this encoding to another mail address field, modify NTS_NAME_LOOKUP_EMAILADDRESSITEMS property. See Address encoding for Microsoft Exchange ActiveSync devices for more information on this function.