Modules

Overview

Modules (or application modules) are the functional components of WebSubmit, allowing users to accomplish tasks on remote systems.  Each module is presented as an HTML form to the user.  They fill out this form as needed and submit it to the WebSubmit server, which then processes the data (using a support script or the module itself) and then forwards any command requests to the desired remote system.  Each WebSubmit module is dynamically generated by a CGI script; this script either comes with the distribution, is automatically generated using a database specification for the form, or was created in some other fashion (and possibly in another development language).

The master database controls what modules appear to users when they try to access the system.  This database also specifies the way in way in which the module is built (i.e., whether it is hand-written or automatically generated).  All module scripts reside in a special directory hierarchy (see Installation notes) $wsRootDir/modules/$hostName/$moduleName, where $hostName is the host that corresponds with the module, and $moduleName is the key used for the given module in the master database.  The processor script is typically located in this directory as well, although it need not be.  The following sections discuss additional aspects of modules and their use in WebSubmit.
 
 

Features of Tcl Modules using WebSubmit

The characteristics discussed in this section are common to many of the WebSubmit modules provided with the distribution.  If a developer is interested in creating new Tcl modules to add to the system, then some of the following features might be included in these modules.
 

WebSubmit Library and websubmit.conf (required for WebSubmit scripts)
WebSubmit code is contained in a series of Tcl packages.  In order to access these packages from a Tcl script, the packages have to be loaded using the Tcl package require command.  package require traverses a directory hierarchy contained in the Tcl variable auto_path looking for the desired packages.  Loading the WebSubmit package(s) requires modifying the auto_path appropriately and then issuing the proper package require command.  The file $wsRootDir/bin/websubmit.conf contains the necessary modifications to auto_path for your site, and issues the package require command.  In addition, websubmit.conf contains the calls to the authentication routines.  Every WebSubmit module should issue the command

to load the WebSubmit libraries.  The scripts that come with the distribution will have this command, provided the distribution has been installed properly using the installation tools that come with WebSubmit.  NOTE: sourceing websubmit.conf is absolutely essential for loading the WebSubmit package and performing the required authentication.
 
 
Session Manager (optional)
Any module that uses WebSubmit session management techniques needs to be carefully configured.  The Session Manager should be present on the form, and the module processing should be set up appropriately.  More information on using session management with scripts can be found in the section on Session Management.
 
 
Online Help (optional)
The footer provided by websubmit.cgi is used to contain help information about specific elements within an application module.  The help text for the application module is currently hard-coded within the script.  The template modules provide examples of how the help information is entered and activated using the javascript code provided with WebSubmit.  Basically, an array is defined that contains the help data for individual elements, and a list of these elements must be provided in HELP(elementList).  Elements are indexed based on the names of the corresponding for element variable, where possible.  After the help information is entered, helpSetup is called with the name of the help data array as its only argument.  Then, within the script definition itself,  links are defined that access the indexed help information.
 
 
 

Creating New Tcl Modules for WebSubmit

The process of creating a new Tcl module for use in WebSubmit basically involves writing the code and adding the necessary calls to WebSubmit routines.  WebSubmit CGI scripts use the cgi.tcl library to generate the desired HTML code.  It is not necessary to use this library in your own scripts, although it would allow other WebSubmit modules to be used as templates.  The only basic requirement for writing a Tcl script that uses all the features of WebSubmit is to load the WebSubmit library using websubmit.conf as detailed above.  Once the script is written and debugged, it can be added to the WebSubmit hierarchy of modules using the installation algorithms above.
 
 
 

Installing Tcl Modules in the System

It should not be difficult to add Tcl modules to the WebSubmit system, since it has been designed with modularity and flexibility in mind.  However, there are a few considerations that need to be kept in mind when installing scripts that do not come with the distribution.

Installation Algorithm
To install a Tcl module in the WebSubmit system, the following algorithm should be utilized.  For the purposes of illustration, we will assume that the module script file is called newModule.cgi and that there are no other modules by the same name.  When installing your own module (with a different name), adjust the required actions in the algorithm accordingly.

  1. Create directory $wsRootDir/modules/hostName/newModule with permissions necessary for CGI accessibility (755 on a UNIX system)
  2. Copy or move newModule.cgi to $wsRootDir/modules/hostName/newModule
  3. Change file permissions on newModule.cgi so that it can be executed in a CGI context (755 on a UNIX system)
  4. Move processing scripts for newModule.cgi into $wsRootDir/modules/hostName/newModule if necessary and change permissions as needed
  5. Add an entry in the master database ($wsRootDir/lib/master.db) with key newModule and data appropriate to the module for the master page
Security Considerations
The WebSubmit security architecture is used to verify users before providing them access to modules.  If a module is installed in the system that does not utilize the WebSubmit package, it is possible that users can simply subvert the verification procedure and access the module directly (without passing through the main WebSubmit entry point).  If the script is written in Tcl, the WebSubmit verification process can be automatically activated by simply loading the WebSubmit package and then sourcing websubmit.conf.
 
 

Installing non-Tcl Modules in the System

In principle, any CGI script (e.g., written in Perl) may be accessed through WebSubmit, although the level of security enabled depends on exactly how the module is accessed.

Case I: No Special Security Precautions
Non-Tcl modules that are accessed without special precautions will not ensure that a given user is registered with WebSubmit.  If the administrator decides that such measures are not needed for a particular script, then it may simply be placed somewhere within the module directory hierarchy as described above.  Provided the master database is configured properly to locate the script, it can be run as usual.

Case II: Non-Tcl script Wrapped inside WebSubmit authentication
If a developer or administrator wants a non-Tcl script to have WebSubmit authentication performed, then the script can be wrapped using a Tcl wrapper utility that comes with the distribution ($wsRootDir/bin/formWrapper.cgi).  In order to prevent direct access to the non-Tcl script, it should be placed somewhere below $wsRootDir/wrap (assuming this directory cannot be accessed directly by your server).  The algorithm for installation of secure, non-Tcl modules is as follows.  Assume that a module called foobar.pl (a Perl script) is to be added to the system.

  1. Determine the desired location for the module in the module hierarchy.  Modules are categorized as either host-specific, or generic.  If host-specific, create the directory $wsRootDir/modules/$host/foobar.  If generic, then create the directory $wsRootDir/modules/generic/foobar.
  2. Create a symbolic link called formWrapper.cgi within the newly created directory that points to $wsRootDir/bin/formWrapper.cgi.
  3. Create another directory: $wsRootDir/wrap/foobar
  4. Place foobar.pl inside $wsRootDir/wrap/foobar and change its permissions to 755.
  5. Add an entry to the master database (master.db, master.txt) for foobar.pl; its build attribute in master.db should be set to WRAP.
  6. Access the module as you would any other WebSubmit module.
The URL for this non-Tcl module will invoke formWrapper.cgi in the foobar directory.  formWrapper.cgi determines the name and location of its parent script (the one being wrapped) using the directory from which it was invoked.  Hence, it is imperative that the correspondence between directory names and script names is maintained.  An example of a non-Tcl script running underneath WebSubmit authentication is provided in $wsRootDir/wrap/testPerl.