Netscape Directory Server Gateway Customization Guide: Chapter 4 Editing Entry Types

Gateway Customization Guide
Netscape Directory Server

Chapter 4 Editing Entry Types

This chapter describes how entry type formats—defined by object classes and their attributes—can be controlled by editing parameters in the dsgw.conf file. The chapter contains the following sections:

Entry Types (Object Classes)

Mapping Locations and Entry Types

Object Class Attributes in Template Files

Entry Types (Object Classes)

The following sections describe entry types in detail:

Parameters Controlling Entry Types

Considerations for Adding New Entry Types

Parameters Controlling Entry Types

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

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

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

Location parameter settings determine where in the directory new entries reside.

Parameters in the dsgw.conf file are described in Appendix A "Parameters Defined in the .conf File."

template

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

location

The location parameter is used to define 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 the entry will be formatted and the location in the directory tree where the entry will be created. Entry types for the default gateway appear in the pop-up menu gateway forms, for instance the Create New Entry form (Figure 4-1).

Figure 4-1    New Entry Form

Considerations for Adding New Entry Types

Before adding support for a new entry type (object class), decide:

Where will the new entry be created?

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

How will the new entry will be 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.

The newtype and location parameters are described in Appendix A "Parameters Defined in the .conf File."

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.

This section explains the following:

Mapping Entry Types to Locations

Configuring DN Formats for Entry Types

Note

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

Mapping Entry Types to Locations

Each entry type must be mapped to a location where that type of entry can be placed. The following example shows a mapping of locations and newtype parameters in dsgw.conf:

location location location location location location location location

country org groups acct hr pay pd test

"United States" "This Organization" "Organizational Groups" "Accounting" "Human Resources" "Payroll" "Product Development" "Product Testing"

"c=US#" "" "ou=Groups" "ou=Accounting" "ou=Human Resources" "ou=Payroll" "ou=Product Development" "ou=Product Testing"

newtype newtype newtype newtype newtype

orgperson NTperson groupun orgunit org

"Person" "NT Person" "Group" "Organizational Unit" "Organization"

cn acct hr pay pd test cn acct hr pay pd test cn groups ou org o country

In the example, locations defined in the newtype parameter (such as country, org, or groups) correspond to handles defined in the location parameter. The friendly names (in quotes) in the third column indicate the choices that will appear in pull-down menus on gateway forms.

Note

Location parameter definitions in dsgw.conf must be listed before newtype parameter definitions.

See Entry Types (Object Classes) for more information.

Setting Up Organizational Units

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

ou=Accounting, o=example.com
ou=Human Resources, o=example.com
ou=Payroll, o=example.com
ou=Product Development, o=example.com
ou=Product Testing, o=example.com
Configuring DN Formats for Entry Types

The following sections describe how to configure entry type DNs depending upon the format.

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 as follows:

newtype orgperson "Person" cn people special

Object Class Attributes in Template Files

The following sections describe the object classes and attributes contained by the template files:

Default Gateway Object Classes

Templates and Directives

Adding Attributes to Object Classes

Deleting Attributes from Object Classes

Extending Object Classes

Creating a New Parent Object Class

Default Gateway Object Classes

The default gateway supports the object classes listed in Table 4-1.

Table 4-1    Default Object Classes

Default Gateway Object Class

Related Template File

domain component

display-dc.html

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

Entry-related directives are responsible for how the gateway displays, edits, adds, and lists directory entries. The most commonly used entry-related directive is DS_ATTRIBUTE, which determines how attributes in LDAP entries are displayed on gateway forms.

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

Appendix B "Gateway Directives" 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 the following example defines an Initials attribute for the orgperson object class:

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

</B></TD>
<TD> </TD>
<TD> </TD>
</TR>
To complete the row, two null cells are added. This maintains the HTML table format. For Asian character sets, substitute an ideographic space for the non-breaking space ( ) shown in the example.

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. The following example shows the steps required to delete the mobile phone attribute from the 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. The following example shows the steps required to add a template for a new object class, examplePerson. The new template adds two custom attributes, dateOfBirth and preferredOS, to the inetOrgPerson object class.

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

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



to



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



to



Add the value for exampleperson 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="exampleperson">

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.

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

template exampleperson person inetorgperson exampleperson

This will instruct the gateway to display the exampleperson entry type according to the template defined for the examplePerson object class (display-exampleperson.html).

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

To allow users to add entries for exampleperson 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.

See Considerations for Adding New Entry Types, and Extending Search Preferences.

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 will instruct 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 will search for entries of this type.

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

Note

Modify an existing search result form to create a new search results form. See Adding Information to Search Results and Removing Information From Search Results.

Default Gateway Object Class	Related Template File
domain component	`display-dc.html`
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`

Last Updated October 31, 2003


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

`location location location location location location location location`	`country org groups acct hr pay pd test`	`"United States" "This Organization" "Organizational Groups" "Accounting" "Human Resources" "Payroll" "Product Development" "Product Testing"`	`"c=US#" "" "ou=Groups" "ou=Accounting" "ou=Human Resources" "ou=Payroll" "ou=Product Development" "ou=Product Testing"`
`newtype newtype newtype newtype newtype`	`orgperson NTperson groupun orgunit org`	`"Person" "NT Person" "Group" "Organizational Unit" "Organization"`	`cn acct hr pay pd test cn acct hr pay pd test cn groups ou org o country`


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


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


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


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.


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.


Note	Modify an existing search result form to create a new search results form. See Adding Information to Search Results and Removing Information From Search Results.