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


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 baseurl, 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.

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 is used to search on object classes defined for the gateway. The advanced search form allows users to search object class attributes and to specify matching patterns (Figure 6.1 shows the entry types that can be selected, Figure 6.2 shows the specific attributes that can be searched on for person entries, and Figure 6.3 shows the matching types that can be specified).

Figure 6.1 Entry Type Pull-Down Menu for Advanced Search Form

Figure 6.2 Attribute Pull-Down Menu on Advanced Search Form

Figure 6.3 Matching Type Pull-Down on Advanced Search Form

Specifying Search Attributes for Person

The dsgwsearchprefs.conf syntax in Example 6.1 specifies that the cn, sn, telephoneNumber, mail, uid, and title attributes are used in a search for person entries.

Example 6.1 Search Attributes for Person Entry

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 Example 6.1 specifies how the LDAP attribute shown in the second column appears in the pull-down menu on the Advanced Search form. Choose one term form menu, or leave out.

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

Table 6.2 Bit Positions and Corresponding Search Match Types


Bit position	Match type	Type of Search Performed
1	contains	Substring search for entries having attributes with values ending wih the specified search sting.
2	ends with	Substing search for entries having attribgutes with values ending with the sspecified search string.
3	starts with	Substing search for entries having attributes with values starting with the specified search string.
4	sounds like	Approximate search for phonetic matches.
5	is not	Equality search for all the entries with attribute value that does not match exactly.
6	is	Equality search for all entries having value that matches exactly.

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 looks for 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.

Adding Search Support for Additional Attributes

The boldface syntax in Example 6.2 shows the addition of preferences for searching the pagerTelephoneNumber attribute.

Example 6.2 Extending Search Preferences to Include Pager Number

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 appears in the pull-down menu on the Advanced Search form.

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

The gateway looks for values that contain, end with, start with, or are identical to the search string entered by the user. It does 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 setting preferences for searching object class attributes and defining a filter to use in expressing search results.

Extending Search Preferences

The boldface syntax in Example 6.3 shows the introduction of a new object, airiusPerson, and a new attribute, dateOfBirth, to the search preferences for the person object class.

Example 6.3 Editing dsgwsearchprefs.conf to Extend a Search Preference

People
""
"Search for":
"(&(objectClass=person)(objectClass=airiusPerson)"
"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 airiusPerson object class in Example 6.3:

The gateway includes airiusPerson entries in its search for persons.

A "birthdate" field appears on the advanced search form.

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

The syntax added to dsgwfilter.conf in Example 6.4 defines the search values for the dateOfBirth attribute.

Example 6.4 dsgw-people entry configured to search for dateofBirth values

"[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

To add a new search object that differs from existing search objects:

add a new entry in dsgwsearchprefs.conf

add a new entry in dsgwfilter.conf

add a new search results template

The syntax in Example 6.5 specifies that the search definition for OrgRole searches the cn, l, roleOccupant, description, and telephoneNumber attributes.

Example 6.5 Creating a new dsgwsearchprefs.conf entry for OrgRole

"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 Example 6.6 specifies a list of filters for searching attributes in the orgRole object class.

Example 6.6 Creating 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 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.

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

Search Filters for User Data Patterns

Example 6.7 shows typical search filter syntax for any search string containing the at (@) symbol. In this example, the gateway responds 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 returns 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).

Example 6.7 Search Filter for Email Address Searches

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

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

Specifying a Search Filter for a New Object

The syntax in Example 6.8 allows users to search person entries by birthday or birth month.

Example 6.8 Modifying a search filter pattern

[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 boldface syntax in Example 6.8 to the dsgw-people entry in dsgwfilter.conf, the gateway also filters the dateofBirth attribute for values that start with the supplied value (the filter). The gateway returns 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 match many different strings.

Customizing 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, Phone Number, E-Mail Address, and Title attributes.

Figure 6.4 Search Results

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

Table 6.3 Default Search Results for Search Objects


Search object	Search result template used	Search results displayed
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

Adding Information to Search Results

The boldface text in Example 6.9 shows how additional information can be added to the search result by modifying the corresponding search result template.

Example 6.9 Adding OrgUnit to Search Results for People

<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>

In Example 6.9, 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.