Netscape Directory Server Gateway Customization Guide: Entry Types and Object Class Attributes

Complete Contents
Preface
Chapter 1 Gateway Features
Chapter 2 Setting Up the Gateway
Chapter 3 Gateway Localization
Chapter 4 Files Controlling Gateway Functionality
Chapter 5 Entry Types and Object Class Attributes
Chapter 6 Search Attributes, Features, and Results
Chapter 7 Customizing Color and Graphics
Appendix A .conf Parameters
Appendix B Gateway Directives Reference
Appendix C CGI Usage
Appendix D Gateway User Help

Contents

Index

Chapter 5 Entry Types and Object Class Attributes

This chapter describes how entry type formats—defined by object classes and their attributes—are controlled by parameters in the dsgw.conf file. Topics include:

Entry Types (Object Classes)

Mapping Locations and Entry Types

Object Class Attributes in Template Files

Entry Types (Object Classes)

Parameters Controlling Entry Types

The functionality of entry types appearing on gateway forms are controlled by parameters stored in dsgw.conf, including:

template parameter settings that determine the types of objects that can be created and the attributes supported for object classes.

newtype parameter settings that determine the DN formats to be applied to new entries.

location parameter settings that determine where in the directory new entries reside.

The template parameter maps the gateway's HTML templates for entry types to the Directory Server's LDAP object classes.

location

The location parameter defines points in the directory tree where new entries can be added. The location parameter definitions must precede newtype parameter definitions in the .conf file.

newtype

Each entry type is described by a newtype parameter. The newtype template indicates how new entries will be formatted and where in the directory tree entries new entries will appear. Entry types for the default gateway appear in the pull-down menu on gateway forms (for instance, the Create New Entry form, Figure 5.1).

Figure 5.1 New Entry Form

Considerations for Adding New Entry Types

Before adding support for a new entry type (object class), decide where in the directory tree the entry type should appear and how the entry type should be formatted.

Deciding where the new entry appears

If a location parameter is not set up to point to the location where the new entry type appears, add a new location parameter to the dsgw.conf file.

Deciding how the new entry is formatted

When the new object class has many attributes in common with an existing entry type, update the corresponding template line in dsgw.conf to support the new object class. When a new object class requires a new template, add a new template parameter to dsgw.conf.

Mapping Locations and Entry Types

The location parameter is used to define points in the directory tree where new entries can be added. The default locations defined in dsgw.conf are intended for the sample directory shipped with the Directory Server. They are unlikely to match the structure of the actual directory.

Note. For simple directory structures, define locations that represent branch points in the directory. For complex structures, define branch points for only the most commonly used directory branches.

Mapping Entry Types to Locations

Each Entry type must be mapped to a location where that type of entry can be placed. Example 5.1 shows a mapping of locations and newtype parameters in dsgw.conf.

Example 5.1 Mapping of Locations and Entry Types in dsgw.conf

location country "United States" "c=US#"
location org "This Organization" ""
location groups "Organizational Groups" "ou=Groups"
location acct "Accounting" "ou=Accounting"
location hr "Human Resources" "ou=Human Resources"
location pay "Payroll" "ou=Payroll"
location pd "Product Development" "ou=Product Development"
location test "Product Testing" "ou=Product Testing"

newtype orgperson "Person" cn acct hr pay pd test
newtype NTperson "NT Person" cn acct hr pay pd test
newtype groupun "Group" cn groups
newtype orgunit "Organizational Unit"ou org
newtype org "Organization" o country

In Example 5.1, locations defined in the newtype parameter (boldfaced) correspond to handles defined in the location parameter (also boldfaced). The friendly names (in quotes) in the third column indicate the choices that appear in pull-down menus on gateway forms.

Note. location parameter definitions in dsgw.conf must be listed before newtype parameter definitions.

Assuming that the root DN is set to o=airius.com, the mappings in Example 5.1 can be used to create people in the following organizational units:

ou=Accounting, o=airius.com
ou=Human Resources, o=airius.com
ou=Payroll, o=airius.com
ou=Product Development, o=airius.com
ou=Product Testing, o=airius.com

Configuring DN Formats for Entry Types

UID-Based DN

When a person or NT person entry is added to the directory, the gateway prompts for a unique DN. The unique DN is typically the user ID of a person in the organization.

Although DN formats can be based on the common names of employees in the organization, common names are frequently not unique within an organization.

Note. UID-based DN formats are recommended because they are by nature unique and can prevent naming collisions within the directory.

Modifying the Default DN format

The default DN format can be modified by editing the rdnattr variable within the newtype parameter.

To change the gateway configuration so that person entries are created using common name-based DNs rather than user ID-based DNs, edit the following line in the dsgw.conf file

newtype orgperson "Person" uid people special

to read

newtype orgperson "Person" cn people special

Object Class Attributes in Template Files

Default Gateway Object Classes

The default gateway supports the object classes listed in Table 5.1.

Table 5.1 Default Object Classes


Default Gateway Object Class	Related Template File
groupOfNames	display-group.html
groupOfUniqueNames	display-groupun.html
ntGroup	display-ntgroup.html
organization	display-org.html
organizationalUnit	display-orgunit.html
person	display-person.html
inetOrgPerson	display-orgperson.html
ntUser	display-ntuser.html
country	display-country.html

Templates and Directives

Object class attributes associated with an entry type are defined by directives contained in gateway template files. Directives are instructions, written as HTML comments, that are interpreted by the gateway's CGI scripts. Each directive is an independent, single line of HTML in a template file (with the exception of , which is embedded within an URL).

Entry-Related Directives

DS_ATTRIBUTE directives begin with a DS_ENTRYBEGIN tag and close with a DS_ENTRYEND tag.

See Also

Appendix B, "Gateway Directives Reference" lists the possible arguments for the DS=ATTRIBUTE directive.

Adding Attributes to Object Classes

Adding an attribute to an object class requires adding an additional row to the HTML table in the template file where the object class is defined.

The syntax in Example 5.2defines an Initials attribute for the orgperson object class.

Example 5.2 Adding Initials attribute to orgperson object class

<TR>
<TD VALIGN= "TOP" NOWRAP>Initials</TD>

To complete the row, two null cells are added. This maintains the HTML table format. For Asian character sets, substitute an ideograhpic space for the non-breaking space ( ) shown in Example 5.2

Note. Attribute values are added in pairs. When adding a single attribute to an object class, remember to complete the table row.

Deleting Attributes from Object Classes

Deleting an attribute from an object class requires deleting a complete row or part of a row from the HTML table where the object is defined. Example 5.3 shows the steps required to delete the mobile phone attribute from the orgperson object class.

Example 5.3 Deleting mobile phone attribute from orgperson object class

Open display-orgperson.html template and delete the mobile phone attribute-value pair (boldfaced text below)

<TR>
<TD VALIGN="TOP" NOWRAP>Pager:</TD>
<TD VALIGN="TOP" NOWRAP><B>

</B></TD>
<TD VALIGN="TOP" NOWRAP>Mobile Phone:</TD>
<TD VALIGN="TOP" NOWRAP><B>

</B></TD>
</TR>

Insert a null pair to replace the deleted attribute (boldfaced below).

<TR>
<TD VALIGN="TOP" NOWRAP>Pager:</TD>
<TD VALIGN="TOP" NOWRAP><B>

</B></TD>
<TD> </TD>
<TD> </TD>
</TR>

Note. When deleting a single attribute-value pair from a row, replace the two deleted cells with two cells containing the non-breaking space character. This maintains the table width and ensures that the background colors are rendered correctly.

Extending Object Classes

The gateway can be extended to support additional object classes. This requires changing information in an existing object class template so that the gateway displays the associated entry type.

Note. When extending object class definitions, the child should appear below the parent object class in the HTML file. Otherwise, the gateway cannot correctly interpret the HTML syntax.

Adding a Template for a Child of a Parent Class

The easiest way to create a new object class is to extend an existing object class template, adding and deleting attributes as necessary. Example 5.4 shows the steps required to add a template for a new object class, airiusPerson, which adds two custom attributes—dateOfBirth and preferredOS—to the inetOrgPerson object class.

Example 5.4 Adding template for subclass airiusPerson

Copy the display-orgperson.html file and rename it as display-airiusperson.html.

Edit the third line in the template file to indicate the name of the new directory entry type. Change:

Edit the DS_OBJECTCLASS directive to include the new object class. Change:

Add the value for airiusperson to the input type.

<INPUT TYPE="hidden" NAME="add_objectClass" VALUE="top">
<INPUT TYPE="hidden" NAME="add_objectClass" VALUE="person">
<INPUT TYPE="hidden" NAME="add_objectClass" VALUE="organizationalPerson">
<INPUT TYPE="hidden" NAME="add_objectClass" VALUE="inetOrgPerson">
<INPUT TYPE="hidden" NAME="add_objectClass" VALUE="airiusperson">

Be sure to add the line immediately before the ENDIF directive:

Add a new table row containing the dateOfBirth and preferredOS attribute-value pairs.

<TR>
<TD VALIGN="TOP">Date of Birth:</TD>
<TD VALIGN="TOP"><B>

</B></TD>
<TD VALIGN="TOP">Preferred OS</TD>
<TD VALIGN="TOP"><B>

</B></TD></TR>

For more information on adding attributes, see "Object Class Attributes in Template Files" on page 50.

Define a template parameter in dsgw.conf for the object class airiusPerson:

template Airiusperson person inetorgperson airiusperson

This instructs the gateway to display the Airiusperson entry type according to the template defined for the airiusPerson object class (display- airiusperson.html).

Update the Directory Server schema to include the airiusPerson object class.

To allow users to add entries for Airiusperson using the gateway, add an additional newtype parameter to the dsgw.conf file. If this entry type is for display purposes only, no newtype parameter needs to be added.

Creating a New Parent Object Class

These steps are required when the object class is not a child of an existing object class.

Add a template parameter to dsgw.conf for the new object class.

template <newobjectclass>

This instructs the gateway to display the associated entry type according to the template defined for the new object class.

To allow gateway users to add entries for the entry type, add an additional newtype parameter to the dsgw.conf file. If the associated entry type is for display purposes only, no newtype parameter needs to be added.

Update the Directory Server schema to include the new object class.

Add a search object entry to dsgwsearchprefs.conf and update dsgwfilter.conf so that the gateway searches for entries of this type.

Create a new search results form defining how the gateway displays search results for the new object class.

Note. Netscape recommends modifying an existing search result form to create a new search results form.