Deploying Red Hat Directory Server Org Chart
Red Hat Directory Server

Red Hat Directory Server Org Chart


Red Hat Directory Server (Directory Server) provides a sample client application named Red Hat Directory Server Org Chart (Org Chart). This document introduces the application, explains how to configure the application to work with your Directory Server and deploy it for use within your organization.

The document contains the following sections:

Introduction to Org Chart

The Org Chart application, when configured to work with an instance of Directory Server, enables viewing of users' organizational hierarchy and associated details, such as designation, contact information, physical location, AIM online status, and so on, in a quick and easy manner. Depending on your directory data and associated applications, you can customize Org Chart to link to many of these applications.

The figure below shows the Org Chart user interface with a sample hierarchy.





By default, the UI shows users' name, designation, email address, manager's name, reportees' names, and provides a link to the company phonebook.

Note that end users too can customize certain aspects of the interface—the Customize link visible to the top-right corner of the UI opens a window with relevant fields to customize the appearance of search results. The figure below shows the Customize View window.





By default, end users can choose to hide the icons, or display them in a floating layer or next to the name of the user. They can also choose the number of levels in the hierarchy they wish to view.

By modifying the default HTML forms and icons, you can change the look and feel of the end user interface.

Integrating Org Chart with Directory Server

To integrate the Org Chart application with your directory, follow these steps:

Step 1. Ensure Prerequisites are Met

For the Org Chart application to work, each user entry in your directory must contain the manager (or a similar) attribute with the DN of the user's manager so that it is possible for the application to determine and then depict the organizational hierarchy for the user. If you do not already have this type of attribute in your directory, it will need to be added; otherwise, Org Chart will not be able to draw the organizational hierarchy for a given user.

Step 2. Install Directory Server

The Org Chart application is installed automatically as part of the Directory Server installation. So, install the server on the machine in which you want Org Chart to be installed. For Directory Server installation or upgrade instructions, check the Red Hat Directory Server Installation Guide.

Step 3. Modify the Configuration File

During the installation, the files relevant to the Org Chart application are placed at this location:

serverRoot/clients/orgchart

The configuration information for the application is stored in this file:

serverRoot/clients/orgchart/config.txt

The file lists parameters (as name-value pairs) that define the functioning of the application. You can modify desired settings in the file and customize the application to suit your organization. See "Org Chart Configuration Parameters" for detailed information on the configuration parameters.

Many of the parameters such as the Directory Server host name, port number, base suffix, and the URL to the Directory Server Gateway derive values from user input during Directory Server installation. After installation, if you view the Org Chart configuration file, you will notice such fields prepopulated with values entered during Directory Server installation.

Also note that the Org Chart application is by default configured to use the Red Hat Administration Server as its web server. This configuration makes the application to work out of the box. That is, you can start using Org Chart by opening a web browser window and accessing http://adminHost:adminPort/clients/orgchart/html/index.html, or by going to http://adminHost:adminPort and clicking the Directory Server Org Charts link.

In both the URLs, adminHost is the fully-qualified host name of Red Hat Administration Server associated your Directory Server, and adminPort is the port number on which Administration Server is listening for requests.

Step 4. Modify the User Interface

If required, you can customize the user interface of the Org Chart application to suit your organization. The files relevant to the user interface are placed in this directory:

serverRoot/clients/orgchart/html

Step 5. Verify Your Configuration

Verify your changes to the Org Chart application by visiting this URL:

http://adminHost:adminPort/orgchart/

or

http://adminHost:adminPort/clients/orgchart/html/index.html

Integrating Org Chart with a Web Server

By default, the Org Chart application is configured to use Red Hat Administration Server as its web server; this configuration makes the application work out of the box. If you prefer to set up your Org Chart to work with a dedicated, high-performance HTTP server (for example, Red Hat Enterprise Server) instead, you will need to make certain modifications:

  1. Change the appropriate host names and port numbers in the Org Chart's configuration file (config.txt). For a list of configuration attributes, see "Org Chart Configuration Parameters".
  2. Add the CGI directories (under Program Management).
    3. Prefix: /clients/orgchart/bin
    CGI Directory: serverRoot/clients/orgchart/bin
     
    On Windows, add the above directories as shell CGI directories.
     
  3. Add an additional document directory (under Content Management).
    4. Prefix: /clients
    Directory: serverRoot/clients
     
  4. Change permissions of the cookie directory (required for UNIX only).

    5. Note  

    The URL format to Org Chart remains the same irrespective of whether you use the Administration Server or a dedicated web server. The only difference is that the application works right out of the box with Administration Server and requires additional configuration changes when using the a web server.



The configuration procedures outlined in this section assume that a Red Hat Enterprise Server is installed and configured to communicate with Directory Server. For Red Hat Enterprise Server documentation, check this site:

http://www.redhat.com/docs/manuals/ent-server/

For configuring other HTTP servers, follow the documentation that came with the product.

To configure Org Chart to work with Red Hat Enterprise Server, follow the instructions below:

  1. Add an additional CGI directory.
    2. Adding an additional CGI directory is necessary to make the Org Chart's CGI programs available. For instructions, refer to the Specifying a CGI Directory section of the Red Hat Enterprise Server Administrator's Guide, available at the aforementioned site.
     
    From the Class Manager for the Red Hat Enterprise Server:
     
    1. Select Programs > CGI Directory.
    2. In the URL Prefix field, enter the URL prefix to use:
      3. /clients/orgchart/bin
       
    3. In the CGI Directory field, enter this (replace serverRoot with your installation directory):
      4. serverRoot/clients/orgchart/bin
       
    4. Click OK, then Save and Apply.
  2. Add an additional document directory.
    3. Adding an additional document directory is necessary to establish access to the Org Chart files. For instructions, refer to the Setting Additional Document Directories section of the Red Hat Enterprise Server Administrator's Guide.
     
    From the Class Manager for the Red Hat Enterprise Server:
     
    1. Select Content Management > Additional Document Directories.
    2. In the URL Prefix field, enter this:
      3. clients/orgchart
       
    3. In the Map to Directory field, enter this (replace serverRoot with your installation directory):
      4. serverRoot/clients/orgchart/
       
    4. Click OK, then Save and Apply.
  3. Change permissions of cookie directory (required for UNIX only).
    4. To be able to store cookies on the HTTP server, the Org Chart must have write access to the HTTP server's cookie directory.
     
    From the Class Manager for the Red Hat Enterprise Server:
     
    1. Select System Settings > View Server Settings and note the value set for the User field.
      2. If this value is set to nobody, check to make sure that the server is not running as a named user. For example, on Solaris grep for the HTTP process:
       
      ps -ef | grep http
       
      The process listed identifies the name under which the HTTP process is running.
       
    2. Log into the machine as root.
    3. Go to the serverRoot/clients/orgchart directory and enter this:
      4. # chown uid authck
       
      where uid is the user name determined in step a.
       
    4. Verify that the directory is accessible by opening this URL:
      5. http://webserverHost:webserverPort/ds/search
       
      where webserverHost is the HTTP server's host name and webserverPort is the port number used by the server. When the HTTP server is using the standard HTTP port number (80), the port number does not need to be included in the URL.
       

Org Chart Configuration Parameters

The Org Chart configuration file (serverRoot/clients/orgchart/config.txt) lists parameters that determine how the application functions. Table 1-1 provides a summary of these parameters.


Table 1-1    Org Chart Configuration Parameters  


Attributes of the Form...

Enable You to ...

allowed-filter-chars

Specify characters that are permitted in the search filter. For details, see:

attrib-*

Specify the Directory Server attributes that you want to be used for both Org Chart generation as well as the final display values. For details, see:

icons-*

Specify the icons that are to be displayed in the Org Chart UI. For details, see:

ldap-*

Specify Directory Server connection details. These parameters derive their default values from your input during Directory Server installation. For details, see:

manager-DN-location

Specify the search method to be deployed to locate the DN values of the manager attribute for a user. For details, see:

max-levels-drawn

Specify the level or depth of organizational hierarchy permitted for viewing.

min-char-searchstring

Specify the minimum number of characters required to initiate directory search. For details, see:

url-*

Specify the base URLs to applications that you want to link from the Org Chart UI. For details, see:



allowed-filter-chars

Specifies the list of characters allowed in search filters. By default, to prevent wild-card searches, the list includes a-z, A-Z, 0-9, _, -, and space.

Format

allowed-filter-chars     allowed_chars

Example

allowed-filter-chars     abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789 _-

attrib-job-title

Specifies the attribute whose value is to be displayed below a user's name in the organizational-hierarchy display. If you don't specify this setting in the configuration file, title will be used as the default.

Format

attrib-job-title     attribute

Example

attrib-job-title     title

attrib-manager

Specifies the attribute whose value is to be displayed as the user's manager's name in the organizational-hierarchy display. If you don't specify this setting in the configuration file, manager will be used as the default. In the absence of the manager attribute, the Org Chart application will fail to depict and draw the organizational hierarchy for the user.

Format

attrib-manager     attributeName

Example

attrib-manager     manager

attrib-farleft-rdn

Specifies the attribute that is being used as the left-most RDN for the DNs of your user entries.

Format

attrib-farleft-dn     attributeName

Example

attrib-farleft-dn     uid

icons-aim-visible

Specifies the display settings for the AIM icon.

Format

icons-aim-visible     displaySettings

displaySettings. Allowed values for the icon-related settings include:

Example

icons-aim-visible     no

icons-email-visible

Specifies the display settings for the Email icon.

Format

icons-email-visible     displaySettings

displaySettings. Allowed values for the icon-related settings include:

Example

icons-email-visible     layer

icons-locator-visible

Specifies the display settings for the Locator icon.

Format

icons-locator-visible     displaySettings

displaySettings. Allowed values for the icon-related settings include:

Example

icons-locator-visible     disable

icons-phonebook-visible

Specifies the display settings for the Phonebook icon.

Format

icons-phonebook-visible     displaySettings

displaySettings. Allowed values for the icon-related settings include:

Example

icons-phonebook-visible     forefront

ldap-bind-dn

Specifies the DN for binding to the Directory Server. For anonymous binding to the server, either remove or comment out the attribute from the configuration file, or leave the attribute value field blank. An attribute name that has no value after it equates to "" for the value.

Format

ldap-bind-dn     "distinguishedName"

Example

ldap-bind-dn     "cn=orgChartUser, o=example.com"

ldap-bind-pass

Specifies the password to use while binding to the Directory Server. For anonymous binding to the server, either remove or comment out the attribute from the configuration file, or leave the attribute value field blank. An attribute name that has no value after it equates to "" for the value.

Format

ldap-bind-pass     "bindPassword"

Example

ldap-bind-pass     "orgChartUserPwd"

ldap-host

Specifies the fully-qualified host name of the machine on which Directory Server is installed.

Format

ldap-host     dirHost

Example

ldap-host     machine.example.com

ldap-port

Specifies the port number on which Directory Server is listening for client requests.

Format

ldap-port     dirPort

Example

ldap-port     389

ldap-search-base

Specifies the distinguished name (DN) representing the point or branch in the directory from which all searches are to be performed. Normally, the search base is set to the directory's suffix or root DN.

Format

ldap-search-base     searchBase

Example

ldap-search-base     dc=example,dc=com

manager-DN-location

Specifies the method of search to be used to retrieve the DN values of the attribute. (The configuration attribute relates to whether a specific assumption should be made on where all values are currently being stored for your manager attribute.)

Based on how your directory information tree (DIT) is configured, there can be two possible scenarios:

For example, assume a user named John Doe with entry DN uid=jdoe, ou=People, dc=example, dc=com. In the Org Chart application, when you enter John Doe to search for and generate the organizational hierarchy, the application tries to look up John Doe's manager's name. The manager-DN-location configuration attribute indicates whether the application should look for the manager attribute values in this same location as that of John Doe's entry (for example, manager = "uid=uboss, ou=People, dc=example, dc=com") or another location.

The configuration attribute supports two options, same and search, for the two scenarios, based on how you have configured your directory information tree:

Format

manager-DN-location     same | search

same. Specifies that the location for all subsequent entries involved in drawing the given Org Chart is the same as the one found for the initial user entry. In other words, this setting assumes a totally flat namespace, at least for all users that will be in a given generated Org Chart.

search. Specifies that other entries that need to be discovered to draw the Org Chart may not be in the same area of the directory tree, and when searching the manager attribute DN values for a given uid, search like this instead:

manager = "uid=jdoe,*"

Typically, this kind of search is time consuming. If your directory deployment fits this scenario, to speed up drawing of the Org Chart as fast as possible, make sure that your Directory Server contains the substring index created for your manager attribute.

The default value (if this setting is not listed in the configuration file) for the manager-DN-location attribute is same.

Example

manager-DN-location     search

max-levels-drawn

Specifies the maximum levels that are allowed to be generated for any given Org Chart; the MyOrgChart version of this setting will never be allowed to be higher than the configured value.

A level is defined as a reporting level for the organizational hierarchy. It means that if you generate an Org Chart for a given person who is a Director, all direct reports to that person are at level 1, people reporting to any of these reportees are at level 2, and so on. So, a setting of 1 would list the full name of the user being searched for and only those people that directly report to that user.

The purpose of having this configuration setting is to give you control over users who may try to generate an Org Chart for the CEO of a company, and thereby heavily tax the Directory Server to generate an Org Chart that may be thousands of people deep.

The default value (if this setting is not listed in the configuration file) for the max-levels-drawn attribute is 3.

The valid range of values for this setting would be a minimum of 1, with no hard-coded maximum.

Format

max-levels-drawn     numberOfLevels

Example

max-levels-drawn     2

min-chars-searchstring

Specifies the minimum number of characters that must be entered in the search request to initiate directory search. That is, users must enter at least this many characters for the Org Chart application to process their request. If they type less characters than the configured value, they will get a message indicating that they need to enter at least n characters to initiate the search, where n will be the configured value.

This configuration setting helps you prevent users from entering LDAP queries for one ot two characters, for example, A or MI, and thus subjecting the Directory Server to search for thousands of results.

Note that this setting is ignored when users search for an exact UID or any other value that's being specified as the leftmost-RDN value (see "attrib-farleft-rdn").

The default value (if this setting is not listed in the configuration file) for the max-levels-drawn attribute is 4.

Format

min-chars-searchstring    numberOfCharacters

Example

min-chars-searchstring     4

url-locator-base

Specifies the base URL for a person-locator type application, thereby providing a link to that application from the Org Chart UI pages; a person-locator type application would show graphically where a given employee's office is located. You specify the partial URL, up until where the user's URL-encoded cn value will be concatenated.

Format

url-locator-base     http://hostname.domain.com/submit.cgi?empfullname=

Example

url-locator-base     http://maps.example.com/submit2.cgi?r_loc=

url-phonebook-base

Specifies the base URL for the Red Hat Directory Express (Phonebook) application, thereby providing a link to the Phonebook application from the Org Chart UI pages. If you want the Phonebook icon visible in the Org Chart UI, you must supply the partial Phonebook URL, which will have each given user's DN attribute value concatenated to the end. In the absence of the url-phonebook-base configuration attribute, there will be no link to the Phonebook application in the Org Chart UI.

By default, the Directory Server installation program sets the base to use the Red Hat Administration Server as the web server. You can change the host name and port number to be that of a dedicated web server. (See "Integrating Org Chart with Directory Server".)

Format

url-phonebook-base     http://adminHost:adminPort/clients/dsgw/bin/dosearch?context=pb&hp=dirHost:dirPort&dn=

Example

url-phonebook-base     http://adminServer.example.com:24020/clients/dsgw/bin/dosearch?context=pb&hp=dirServer.example.com:389&dn=



© 2001 Sun Microsystems, Inc. Used by permission. © 2005 Red Hat, Inc. All rights reserved.

 last updated April 7, 2005