The installation for the Intranet Corporate Directory (hereafter referred to as the Corporate Directory or simply Directory) is a self installing file that asks you several questions about your web site in order to determine where to put it's various components. Some of these questions are technical and may require information from your webmaster. You may want to contact your webmaster before proceeding because this installation requires a fairly good understanding of the structure of your website and may require additional settings on your HTTP server if it is not configured to run CGI programs.

After the license agreement and the welcome dialog, you can select the components you wish to install and the directory for the server. You will almost always want to install all of the components unless you are simply upgrading your system and you don't want to overwrite your existing template files (assuming you have changed them to reflect your company name and logo).

The directory you choose for the server should not be accessible through the web server. The only files that need to be directly accesses by the HTTP server are the CGI programs and the HTML template files. You will be prompted in a moment for the path for these files.

HTML File Location

Next, the installer needs to know where you would like to put the HTML template files. These are the files that your user's will access through your server. You will need to specify both the logical path where you want these files to reside and the URL that will be used to access them.

For example, if you want your users to be able to use http://www.abc.com/corpdir/index.htm to access your Corporate Directory and your web site's document root is at c:\website\documents, then you would specify the following as the path and URL for the HTML template files:

Path: c:\website\documents\corpdir\

URL: http://www.abc.com/corpdir/index.htm

If you are reinstalling or upgrading your installation and you didn't uninstall the previous installation, the installer will load these parameters from your corpdir.ini file.

CGI File Location

Since the HTTP server is often configured to allow CGI execution in only one directory, you must also specify where the Directory CGI programs will be placed. The default for these files is in a directory called "cgi-bin" under your web site's document root directory. Again, you must specify both the logical path where these files will be placed and the URL used to access them through a client's browser.

If your HTTP server is not configured to run CGI programs, you must first enable CGI for cdcgi.cgi and maintcd.cgi. Please refer to your server's documentation for instructions on how this can be done using your server.

WARNING: if you change the default location for the CGI programs such that they can't be referenced using "/cgi-bin/cdcgi.cgi" in your browser, then you must manually modify the three HTML template files to reflect this new relative directory. These files are called index.htm, list.htm, and details.htm.

Direct or Email Approved Updates

If you are installing Corporate Directory Gold, you have the option to either have user's directly update records in the database or have the update request sent to an email address for approval. If you are installing the Silver version, you will automatically proceed to the next question.

Direct updates are much simpler to manage and allow users to make any changes or add new people as it is needed. Unfortunately, it also makes it trivial for them to make unauthorized changes. You will need to carefully weigh the benefits and drawbacks to using direct updates. If you choose to make direct updates, please note the logging options below. They might allow you to track down any unauthorized and undesirable changes made to the Directory.

Email Settings

If you have chosen Email approved updates or you are installing the Silver version of the Directory, you will be asked for the email address of the person who will be responsible for screening and making all changes to the database. You will also need to know the name or IP address of your SMTP mail server. Usually this is mail.yourcompany.com but your system may use a different name or you can use the IP address of the computer running the mail server. Please note that this server must be an SMTP capable email server.

The Supervisor must be the email address of the person who is responsible to screen all updates.

All of the information for the Corporate Directory is stored in a database table. You can use any database for which ODBC drivers are available. The sample database included with the installation is a Microsoft Access database because the ODBC drivers for this database are readily available.

The structure of the database is fairly flexible but there are several requirements that must be followed. The first three fields in the database table are required and are used for identification. The first field must be a unique numeric identifier. The second and third fields are usually the last name and first name respectively. These two fields are used to create the title on the details HTML page. It doesn't matter what names you use for these three fields but all field name are displayed on the details page except for the first field.

You also have the option of defining a field called "Photo" that should contain a URL (either relative or absolute) to the picture of the individual. This picture is usually in .gif or .jpg format and must be created and placed on your web site in the location referred to by this field. Usually this will be a subdirectory in the same directory as index.htm, list.htm, and details.htm. If a photo field is present in the database and it contains a value, the Corporate Directory will attempt to display it in a box immediately to the left of the other information on the details page.

You may include as many other fields as you would like. Keep in mind that the field names will appear as the label for that field and all fields will be placed in a single line entry field except for any field defined as a memo. All fields are scanned for email addresses and URLs. If any are found, they are placed as hyperlinks below the entry field in which they occur. This allows the user to click on the link and go directly to the site or send an email message.

Populating the Database

The simplest method for populating the Corporate Directory depends on the type of database you will use to serve the Directory and the current format of the information your want to include in the Directory. If you are going to use a Microsoft Access database (perhaps replacing the information from the sample database), it would probably be easiest to open the database using Microsoft Access and import your data using the numerous import facilities available in Access.

The DB setting is the data source name in the ODBC Administrator for the Corporate Directory. The ODBC Administrator is located in the Control Panel and the data source for the Corporate Directory must be added before you can run the system. Depending on the type of database you are connecting to, it may require a user name (UID) and password (PWD). Please note that the semi-colons are required if you include a user name or password. The sample Access database included with the installation should be called "CorpDir" and does not require a user name and password.

The DBTable setting is the name of the table in the data source that contains all the Corporate Directory information. The default name in the included sample database is "Directory".

The UpdateType setting specifies either the Direct or Mail (Email) update method. Direct updates make changes directly to the database while Email updates send the update request to the email address specified by the "To" setting below. When email updates are used, the individual who receives the requests is responsible to screen the requests and make the changes using standard database tools. Using this setting helps to prevent unwanted or malicious modifications but requires more work to maintain the directory. If you use Direct updates, you should always run the directory with logging enabled (use the /L command-line parameter) so that you can trace the time and IP address of any changes that are made when disciplinary action is necessary. If you expect this could be a problem, you might want to inform your users that all changes can be traced to the computer that made the request.

The DetailedSearchResults setting indicates whether or not to display the content of memo fields in the search results list. Please note that this setting only affects the display and that all fields are always used in the search. When this is set to "no" it often makes the list more readable.

When set to "no", the AllowEdits setting removes all edit boxes from the user's display making it impossible to make any modification to the Directory.

[Directories]

The StartPagePath setting indicates the path to the directory containing the Corporate Directory index.htm.

The StartPageURL is like the StartPathPath except that it is the URL to the directory containing the Corporate Directory index.htm.

The KBPath setting is the path to the directory containing the Corporate Directory knowledgebase. The knowledgebase is created from the database and generally resides in the same directory as CORPDIR.EXE. Whenever an entry is modified in the database (when using direct updates), the knowledgebase is recreated from the database.

The UpdateURL setting is the URL to the page the user should see after submitting an update request. This defaults to the index page but you may want to create an intermediate page that tells the user about how long it will take for their request to be processes (based on your system configuration and policies if you are using email updates) or you may want to send them to your home page.

The FullMailURL setting is the URL to the CGI program that takes the HTML form and sends it as an email request. The default location for this program is a subdirectory (physical or virtual) off of your web server's root document directory. The CDCGI.CGI program included with the Corporate Directory is capable of sending the message in SMTP format but you may also direct the form to another program for special handling. This may be required if you are not using SMTP (internet) mail and you still want to use email updates. In this case you would need to create a CGI program that would take the content of the form and construct a mail message that conforms to your email specifications.

The FullMaintURL setting is the URL to the CGI program that processes the actual update requests (when using direct updates) and the request to rebuild the knowledgebase. This should almost always point to the MAINTCD.CGI program included with the Corporate Directory. You may want to change the default directory for this request which may include sending the request to a secure server.

The FullCDURL setting is the URL to the CGI program that processes search requests. The default is the CDCGI.CGI program included with the Corporate Directory.

[Mail]

The From setting is used during email updates as the From line in the email message.

The To setting specifies the email address for the person who will screen all updates to the directory. This must be a valid email address or the requests will not reach the intended person.

The Subject setting is displayed as the subject for all email update requests.

The Server setting is the name or IP address of the computer that services your SMTP mail. If you specify a name (often "mail.company.com") it must resolve to the correct IP address. If you are not sure about this name, go to a command prompt and type "ping mail.company.com" to see if you can contact the name in question.

Configuring the Corporate Directory as a Service

The Corporate Directory server can be installed as a service on NT. This may be useful if you want to have the Corporate Directory automatically start without having to log in whenever the server is rebooted.

Installing

You will need to run corpdir.exe with the /InstallAsService command line parameter to add it as a service.

Syntax:

corpdir.exe /InstallAsService:ServiceName /SDstartpath knowledgebase

ServiceName -- the internal name you want to use for this particular instance of the server. The default is "Corpdir Service" but if you are running several servers that all need to be installed as services, you will need to use a unique name for each one. See "Running Multiple Servers" for more details on why you may would want to run several servers and how to do it.

knowledgebase -- the name of the knowledgebase that will be used by this server. When the server starts, it will look for a file called knowledgebase.kb or knowledgebase.kbf. It will also load the knowledgebase.ini file for all necessary settings. When running multiple servers, this name does not have to be unique (unlike the /N parameter) as long as the files for each system are placed in separate directories.

Please note that any additional parameter (such as /L for logging and /SD to specify the starting directory) will be used any time the service is started. You must use the /SetServiceParams parameter to change these settings once it is installed as a services.

Example

The following example will install the Corporate Directory with a service name of "ABC Inc Corpdir Service" with a starting directory of c:\corpdir and will enable logging to the default log file (cdserver.log).

corpdir.exe "/InstallAsService:ABC Inc Corpdir Service" /sdc:\corpdir /L /Nabccorpdir corpdir

Changing Service Parameters

Once the Corporate Directory has been installed as a service, you must use the /SetServiceParams parameter to change the startup parameters for this service. The syntax is identical to the /InstallAsService parameter.

Removing the Service

Use /RemoveAsService:ServiceName to remove (uninstall) the Corporate Directory as a service. You must use the service name that appears in the Control Panel.

Running Multiple Servers

Once you have the Corporate Directory installed and in use, you may find a number of other applications that would be well suited for this type of search capability. You might want to include an intranet rolodex of clients rather than employees or you might want to server several divisions within your company as separate systems.

It is fairly trivial to accomplish if you remember four things:

1) Each application must have it's own server running under a different name (using the /N command-line parameter

2) Each application must have it's own set of HTML template files (in their own directory on the web site) that include a unique name for the "cdcgi_server=name" parameter. This name must match the /N command-line parameter name.

3) Each application must have it's own .ini file that again matches the knowledgebase command-line parameter (i.e. rolodex.ini or marketing.ini)

4) Each application must have it's own database (or table within the same database) that is referenced by the "DB" and "DBTable" ini settings.

You do not need to duplicate the cgi programs or the corpdir.exe server. Simply call the server with a different name for each server you want to add.

Appendix A