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.

dsgwfilter.conf

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

• Pattern for which to search.
• 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.

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.

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

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.

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"

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

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