Chapter 6   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. Topics covered include:

• 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 Results Templates

Search Configuration Files

---

dsgwsearchprefs.conf and dsgwfilter.conf 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

dsgwsearchprefs.conf 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 6-1.

Table 6-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 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 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 6-1, shows the matching patterns that can be selected in the advanced search form.

Figure 6-1    Entry Type Pop-up Menu for Advanced Search Form

Figure 6-2    Attribute Pop-up Menu on Advanced Search Form

Figure 6-3    Matching Filter Pop-up on Advanced Search Form

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 6-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 6-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, siroePerson, and a new attribute, dateOfBirth, to the search preferences for the person object class.

People
""
"Search for":
"(&(objectClass=person)(objectClass=siroePerson)"
"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 siroePerson 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.

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

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

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>
<!-- DS_ATTRIBUTE "attr=dn" "syntax=dn" "label=" -->
onMouseOver="window.status='Click here to view this entry in detail'; return true">
<!-- DS_ATTRIBUTE "attr=cn" "numfields=0" "defaultvalue=name" "options=readonly" -->
</A>
<TD NOWRAP>
<!-- DS_ATTRIBUTE "attr=telephoneNumber" "syntax=tel" -->
<TD NOWRAP>
<!-- DS_ATTRIBUTE "attr=mail" "syntax=mail" -->
<TD NOWRAP>
<!-- DS_ATTRIBUTE "attr=title" --></TD>
<TD NOWRAP>
<!-- DS_ATTRIBUTE "attr=ou" "syntax=cis" --></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 insensitiv.

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 <!-- DS_ATTRIBUTE "attr=ntuserdomainid" "syntax=ntdomain" --> directive would also need to be removed.