Netscape Directory Server Gateway Customization Guide: Chapter 5 Search Attributes, Filters, and Results

Gateway Customization Guide
Netscape Directory Server

Chapter 5 Search Attributes, Filters, and Results

This chapter describes the files that control how the gateway searches for objects and describes how to add search support for a new object. The chapter contains the following sections:

Search Configuration Files

Changing Search Scope

Modifying Search Attributes for Advanced Searches

Adding Search Support for a New Object

Modifying Default Search Filters

Customizing Search Result Templates

Search Configuration Files

The dsgwsearchprefs.conf and dsgwfilter.conf files are the search configuration files that control the gateway's search functionality. These files are stored in the gateway's template directory (/config for the default gateway).

dsgwsearchprefs.conf

The dsgwsearchprefs.conf file specifies the preferences for searching object classes defined in the gateway. Each entry contains:

The scope of the search within the Directory Server

The search filter to append to the search string (corresponding to the search filter entry defined in dsgwfilter.conf)

The label of the search attribute as it is displayed in the Find drop-down list on the Search form

The object class attribute to search on

Match types to use in search results

Note

Define new search preferences in dsgwsearchprefs.conf whenever a new object class with searchable attributes is added to the gateway.

dsgwfilter.conf

The dsgwfilter.conf file contains an entry for each search object defined in dsgwsearchprefs.conf. Each entry defines the following:

Pattern to search for

Delimiters for the search pattern

LDAP filter for generating search results

Text to use in describing search results for the pattern

Scope of the search (not required)

The name of the search filter entry for a search object is identified in dsgwsearchprefs.conf.

Changing Search Scope

Search object entries in dsgwsearchprefs.conf define the search scope used in searches for the corresponding object class. The default scope for gateway search objects, subtree, specifies the baseurl and all its children.

The scope of a search object can be changed by editing the corresponding line in dsgwsearchprefs.conf. Valid search scopes are shown in Table 5-1.

Table 5-1    Valid Search Scopes

Search Scope

Tells the Gateway to...

base

Search the Directory Server for the entry specified in the baseurl parameter but do not search in children of the entry.

onelevel

Do not search in the entry specified in the baseurl parameter, but search in the most immediate children of the entry.

subtree

Search the entry specified in the baseurl parameter and all of it's children. This is the default setting.

Modifying Search Attributes for Advanced Searches

Each search object entry in dsgwsearchprefs.conf has a list of attributes that can be modified for advanced searches. This section explains the following:

Standard and Advanced Searches

Specifying Search Attributes for Person

Directory Express Search Support for User ID

Adding Search Support for Additional Attributes

Standard and Advanced Searches

An advanced search differs from a standard search in that users are provided with a pull-down menu of search types. In the default gateway, the Standard Search form searches on object classes defined for the gateway. The Advanced Search form allows users to also search in specific object class attributes and to specify a matching pattern. Figure 5-1 shows the Advanced Search form with search results.

Figure 5-1    Advanced Search Form: Search Results

The figures that follow show the matching patterns that can be selected in the Advanced Search form.

Figure 5-2 shows the entry type pop-up menu on the Advanced Search form.

Figure 5-2    Advanced Search Form: Entry Type

Figure 5-3 shows the attribute pop-up menu on the Advanced Search form.

Figure 5-3    Advanced Search Form: Attribute

Figure 5-4 shows the matching filter pop-up menu on the Advanced Search form.

Figure 5-4    Advanced Search Form: Matching Filter

Specifying Search Attributes for Person

The dsgwsearchprefs.conf syntax in the following example specifies that the cn, sn, telephoneNumber, mail, uid, and title attributes will be used in a search for person entries:

People
""
"Search for":
"(&(objectClass=person)"
"dsgw-people"
subtree
"full name"         cn     111111 "" ""
"last name"         sn     111111 "" ""
"phone number"         "telephoneNumber"     111011 "" ""
"e-mail address"         "mail"     111111 "" ""
"user id"         "uid"     111111 "" ""
"title"         title    111111 "" ""
END
"is"    "(%a=%v))"
"is not"    "(!(%a=%v)))"
"sounds like"    "(%a~=%v))"
"starts with"    "(%a=%v*))"
"ends with"    "(%a=*%v))"
"contains"    "(%a=*%v*))"
END
The first column in the example specifies how the LDAP attribute shown in the second column appears in the drop-down menu on the Advanced Search form.

The third column contains a string of six bits. Each bit position in the string maps to a match type, as shown in Table 5-2. A value of 1 indicates that the match type is valid for the associated attribute. A value of 0 indicates that the match type is not valid. In the example, the bit position for the telephone number attribute is set to 0, indicating that the Directory Server will not search for sounds like match types for phone number entries on the Advanced Search form.

Table 5-2    Bit Positions and Corresponding Search Match Types

Bit Position

Match Type

1

contains

2

ends with

3

starts with

4

sounds like

5

is not

6

is

The fourth and fifth columns in the search attributes contain empty strings required by the gateway. These should not be altered.

Directory Express Search Support for User ID

Directory Express does exact matches for user ID strings. It does not attempt to match user ID substrings.

To configure substring matching for user IDs, substring index the uid attribute and uncomment the appropriate lines in pbconfig/dsgwfilter.conf and comment out the corresponding lines.

Adding Search Support for Additional Attributes

The boldfaced syntax in the following example specifies preferences for searching the pagerTelephoneNumber attribute.

People
""
"Search for":
"(&(objectClass=person)
"dsgw-people"
subtree
"full name"    cn      111111 "" ""
"last name"         sn      111111 "" ""
"phone number"         "telephoneNumber"      111011 "" ""
"e-mail address"         "mail"      111111 "" ""
"user id"         "uid"      111111 "" ""
"title"         title     111111 "" ""
"pager number"          pagerTelephoneNumber     111011         "" ""
As a result of adding this syntax to dsgwsearchprefs.conf:

A pager number selection will appear in the drop-down menu on the Advanced Search form.

The gateway will search the pagerTelephoneNumber attribute of all entries within the scope of the search.

The gateway will look for values that contain, end with, start with, or are identical to the search string entered by the user. It will not look for values that sound like the search string entered by the user.

Adding Search Support for a New Object

There are two ways to add search support for a new object:

Update entries in dsgwsearchprefs.conf and dsgwfilter.conf with definitions of search attributes for the new object. Use this method to add search support for an object that is a child of another object.

Create new entries in dsgwsearchprefs.conf and desgwfilter.conf for a new object class. This method requires specifying preferences for searching object class attributes and defining a filter to use in expressing search results.

Extending Search Preferences

The boldfaced syntax in the following example shows the introduction of a new object, examplePerson, and a new attribute, dateOfBirth, to the search preferences for the person object class.

People
""
"Search for":
"(&(objectClass=person)(objectClass=examplePerson)"
"dsgw-people"
subtree
"full name"         cn      111111 "" ""
"last name"         sn      111111 "" ""
"phone number"         "telephoneNumber"      111011 "" ""
"e-mail address"         "mail"      111111 "" ""
"user id"         "uid"      111111 "" ""
"title"         title     111111 "" ""
"birthdate"      dateOfBirth          111011         " "     " "
As a result of adding the syntax shown in the example:

The gateway will include examplePerson entries in its search for persons.

A birthdate field will appear on the Advanced Search form.

The gateway will search the dateofBirth attribute of all entries within the scope of the search.

The syntax added to dsgwfilter.conf in the following example defines the search values for the dateOfBirth attribute:

"[0-9][0-9]/[0-9][0-9]/[0-9]0-9]" " " "
    (dateOfBirth=%v))" "date of birth is"
    (dateOfBirth=%v*))" "date of birth starts with"
Creating a New Search Object

Adding a new search object that is not similar to existing search objects requires:

A new entry in dsgwsearchprefs.conf

A new entry in the dsgwfilter.conf

A new search results template

The syntax in the following example specifies that the search definition for OrgRole will search the cn, l, roleOccupant, description, and telephoneNumber attributes:

"Org-Roles"
""
"Search For:"
"(&(objectClass=organizationalRole)
"dsgw-orgrole"
not-used-by-dsgw
not-used-by-dsgw
subtree
"name"        "cn"    111111 "" ""
"location"        "l"     111111 "" ""
"occupant"        "roleOccupant"     111111 "" ""
"description"        "description"    111011 "" ""
"phone number"        "telephoneNumber"     111011 "" ""
END
"is"        "(%a=%v))"
"is not"         "(!(%a=%v)))"
"sounds like"        "(%a~=%v))"
"starts with"         "(%a=%v*))"
"ends with"         "(%a=*%v))"
"contains"         "(%a=*%v*))"
END
The syntax in the above example specifies a list of filters for searching attributes in the orgRole object class.

This example creates a new dsgwfilter.conf entry for orgrole:

dsgwfilter.conf:
dsgw-orgrole"
"="    " "    "(%v))"    "LDAP filter is"

"^[+]*[0-9][ 0-9-]*$"    " "    "(telephoneNumber=*%v))"    "phone number ends with"
"^\*$"    " "    "(cn=*))"    "name is"
".*"    ". _"    "(cn=%v1-))"    "name is"
        "(cn=*%v1-*))"    "name contains"
        "(cn~=%v1-))"    "name sounds like"
Modifying search results forms is described in Modifying Search Result Templates.

Modifying Default Search Filters

The gateway uses dsgwflter.conf to map patterns in search strings to a relevant search filter and search result description (a search pattern is a grep-style regular expression). dsgwwfilter.conf can be optimized to respond to common user data patterns.

Modify existing search filters in dsgwfilter.conf to support new user data patterns, instead of creating new filters.

The sections that follow explain:

Search Filters for User Data Patterns

Specifying a Search Filter for a New Object

Search Filters for User Data Patterns

This example shows typical search filter syntax for any search string containing the @ symbol. In this example, the gateway will respond to search strings containing the @ symbol (the pattern) by searching the mail attribute for values that are equal to or start with the supplied value (the filter). The gateway will then return a message on the search results form indicating the number of entries where the "email address is" or "email address starts with" the user-supplied value (the description).

"@"    " ""(mail=%v))"    "email address is"
    "(mail=%v*))"    "email address starts with"

Note

Standard searches use only the filters associated with the first matching pattern. Advanced searches use all filters defined for the entry.

Specifying a Search Filter for a New Object

The syntax in the following example allows users to search person entries by birthday or birth month:

[0-9][0-9]/[0-9][0-9]/[0-9]0-9](dateOfBirth=%v))date of birth is
dateOfBirth=%v*))date of birth starts with
As a result of the adding the line dateOfBirth=%v*))date of birth starts with to the dsgw-people entry in dsgwfilter.conf, the gateway will also filter the dateofBirth attribute for values that start with the supplied value (the filter). The gateway will return a message on the search results form indicating the number of entries where the "date of birth is" or "date of birth starts with" the user-supplied value (the description).

Note

Make sure to place new patterns near the top of the pattern definitions for a given object. For example, in the dsgw-people entry, place customized patterns before the pattern that begins with the @ symbol. Patterns near the end of the entry are more general, and will match many different strings.

Customizing Search Result Templates

The following sections describe how the gateway displays search results and contains procedures for customizing the gateway search result templates:

How the Gateway Displays Search Results

Modifying Search Result Templates

How the Gateway Displays Search Results

When a user submits a standard search or advanced search from the gateway, the gateway constructs a search string and filter for the corresponding search object and queries the Directory Server. The Directory Server responds with matching entries in the LDAP database. The gateway uses a search result template to display the entries returned by the Directory Server.

Search Result Tables

Search results are displayed as tabular data. Headings in each result tables reflect the object attributes identified in the search result template.

For example, the heading row on the search results form for a People search displays the Name, User ID, Phone Number, E-Mail Address, and Group attributes.

Figure 5-5    Search Results

Table 5-3 lists the default gateway search objects and the information displayed on the search results list. Search results templates are stored in the serverRoot/clients/dsgw/config directory and use the list-<search object>.html file naming convention.

Table 5-3    Default Search Results for Search Objects

Search Object

Search Result Template Used

Search Results Displayed

Domain Component

list-Domaincomponent.html

Organization name, description, and phone number

people

list-People.html

Name, phone number, e-mail address, and title

NT-people

list-NT-People.html

Name, NT domain, NT username, and phone number

Groups

list-Groups.html

Group name and description

NT-Groups

list-NT-Groups.html

LDAP group name, NT domain name, NT group name, and description

Organizations

list-Organizations.html

Organization name, description, and phone number

Org-Units

list-Org-Units.html

Organizational unit name, description, and phone number

Anything

list-Anything.html

Name, phone number, e-mail address, and description

A new search result template is required for each new object class that is not a child of another object class.

Modifying Search Result Templates

This section covers:

Adding Information to Search Results

Removing Information From Search Results

Adding Information to Search Results

This example shows how additional information can be added to the search result by modifying the corresponding search result template.

<TR>
<TH NOWRAP>Name<TH NOWRAP>Phone Number<TH NOWRAP>E-Mail Address<TH NOWRAP>Title<TH NOWRAP>Organizational Unit
</TR>
<TR>
<TD NOWRAP>

onMouseOver="window.status='Click here to view this entry in detail'; return true">

</A>
<TD NOWRAP>

<TD NOWRAP>

<TD NOWRAP>
</TD>
<TD NOWRAP>
</TD>
</TR>
The additional HTML table heading syntax adds the Organizational Unit label to the heading row of the table. The additional DS_ATTRIBUTE directive syntax adds a cell to the body row of the table indicating that the information is stored in the ou attribute of the entry and the string is case insensitive.

Removing Information From Search Results

To remove information from a search result, remove the tag that creates the table head cell labeling the attribute and the tag that creates the Directory Server call for the corresponding attribute value from the corresponding list-<search object>.html file.

For example, to remove the NT Domain attribute from the list-NT-People.html search results file, delete the <TH NOWRAP>NT Domain tag from table heading. The table cell containing the  directive would also need to be removed.

Search Scope	Tells the Gateway to...
`base`	Search the Directory Server for the entry specified in the `baseurl` parameter but do not search in children of the entry.
`onelevel`	Do not search in the entry specified in the `baseurl` parameter, but search in the most immediate children of the entry.
`subtree`	Search the entry specified in the `baseurl` parameter and all of it's children. This is the default setting.

Bit Position	Match Type
1	contains
2	ends with
3	starts with
4	sounds like
5	is not
6	is

Search Object	Search Result Template Used	Search Results Displayed
Domain Component	list-Domaincomponent.html	Organization name, description, and phone number
people	`list-People.html`	Name, phone number, e-mail address, and title
NT-people	`list-NT-People.html`	Name, NT domain, NT username, and phone number
Groups	`list-Groups.html`	Group name and description
NT-Groups	`list-NT-Groups.html`	LDAP group name, NT domain name, NT group name, and description
Organizations	`list-Organizations.html`	Organization name, description, and phone number
Org-Units	`list-Org-Units.html`	Organizational unit name, description, and phone number
Anything	`list-Anything.html`	Name, phone number, e-mail address, and description

Last Updated October 31, 2003


Note	Define new search preferences in `dsgwsearchprefs.conf` whenever a new object class with searchable attributes is added to the gateway.


Note	Standard searches use only the filters associated with the first matching pattern. Advanced searches use all filters defined for the entry.


Note	Make sure to place new patterns near the top of the pattern definitions for a given object. For example, in the `dsgw-people` entry, place customized patterns before the pattern that begins with the @ symbol. Patterns near the end of the entry are more general, and will match many different strings.