Home

KEYSEARCH

KEYSEARCH is a cgi program that has been designed to be a study aid. Using this program a teacher can create web pages containing study questions. The student's answer is analysed and a response to the student is provided based on an analysis of that specific answer. Such responses can go well beyond the usual "correct/incorrect" that an examination program might provide. Hopefully such nuanced responses will focus the student's on-going study.

Overview of Operation

KEYSEARCH has three components. The web page: which is where the question is posed: the student provides the answer to the question in this page and submits it. The Response Logic File (RLF): this contains the data KEYSEARCH needs to analyse the student's answer and to feed the response back to the student, and finally... The response log: this contains a log of the student answers, plus the responses that KEYSEARCH produces. Using the log file the instructor can modify the RLF better to respond to the answers the real students are providing (distinguishing from faculty pretending to be students).

KEYSEARCH works by searching for "keywords" which can be words, word fragments or phrases in the answer that the student provides. Since the web cgi interface is very general the instructor can create questions that use combinations of checkboxes, radio buttons, textareas or pull-downs as tools to build the study questions and elicit answers.

The program generates "html" output by default. However, it can optionally produce JSON data if KEYSEARCH is needed as a logic engine in a web service.

To make the program work, the instructor must create both the web page and prepare the RLF. The balance of this document describes how to do that.

KEYSEARCH Installation

KEYSEARCH is available on several platforms. So far Red Hat Linux is in active use, and MacOSX and OpenVMS have been tested and appear to work well.

Step 1: Get the software The software is most conveniently obtained from its SourceForge repository using "git"; going forwards this will be the only source for up-to-date code. Once the local "git" repository is created the "git pull" command causes the latest updates to the software, including the new executables, to be copied to the local repository from SourceForge. Once you have downloaded the software, the easiest way to use it will be to copy the pre-built executable to the cgi-bin area on the web server.

Step 2: Create needed directories The webmaster/system manager of the web server to be used must install the program in the cgi area and then provide the instructor with read/write access to two areas: the location of the web pages and to a directory where the response logic files can be created and edited. The webmaster also needs to create a directory tree in the web area where the log files can be placed. For "neatness" each course directory should be password protected to allow selective web access to the student responses. Finally, the instructor needs to be added to the mail alias file that allows e-mail feedback from the questions to the instructor.

At this point, we hope, you may be ready to go. However...

Other (optional) issues

If you wish to compile the FORTRAN and re-link, read the instructions at the beginning of the source plus the platform-specific notes. The main motivation for a re-compilation would be to change the size parameters for key variables (in the "params" module) or, more importantly, to change the default paths to the RLF, logs, server name, etc. (in the "setup" module). These two modules are found at the beginning of the source code: nothing else should need to be edited. The package should be self-contained and the code has been compiled successfully and runs on OpenVMS (AXP and I64), Tru64-UNIX, and Solaris and using the Absoft and Intel compilers for OSX and Red Hat Linux and I presume it will compile with the Absoft and Intel compilers for Windows.

The main source of potential problems is that of getting the permissions correct for the executable and the directories and paths to where the RLFs are read and the reviews are written. An experienced system manager for your platform can be invaluable for getting these issues resolved. Note also, that if JSON output is required KEYSEARCH uses an intermediate scratch file that it puts into /tmp/Keysearch/: the location of the scratch area can be fixed in the "params" module if necessary.

On UNIX the web server, usually Apache, generally runs under the account "nobody". So the log entries can only be written if "nobody" has owner or group write permission for the directories where logs are to be written: it isn't a good idea to allow "world" write to the log areas (although this may be what you have to have set to get it running initially.)

On OpenVMS with CSWS 2.1-1 and above (Apache v2.0-x) proper ACLs to provide (read+write+execute) access as appropriate are needed for ALL the files that KEYSEARCH uses, including the utility programs and scripts. This can be a bit challenging to achieve but HP's installation web page for CSWS is a big help. The result is a very secure installation of the software which should meet any server-side security requirements that might be needed for web-based student testing (securing desktops is another issue of course). Good luck!

KEYSEARCH Maintenance

Before committing to use "KEYSEARCH" you need to understand the issues associated with maintaining material written to use it. There are, essentially, three levels with different degrees of "maintainer" sophisication needed for each level. We'll take as an example, a quiz that needs to be kept fresh and useful as its course evolves.

The base level is straight forward. To keep the quiz up-to-date the base-level maintainer needs to be able to create and refresh questions. In the examples provided we have a simple text file containing the quiz items drawn from an item bank and formatted so that a script can "explode" the file into the quiz component files that will be seen by the quiz scripts. The maintainer's tasks are, therefore, (1) to extract questions from the item bank; (2) to verify that the format of the items are "html-ready"; (3) to run the reformatting script provided by the original designer and (4) to adjust the introductory web pages to reflect any change in the number of quiz items, test duration and quiz start and stop dates. Maintainer skills (for these tasks) include the ability to run a script at the command line and to perform basic editing of a web page. While reading this document would be interesting and informative, the base-level maintainer doesn't really need to know anything about "Keysearch" per se and need not ever read this manual.

The designer level maintainer is an individual who creates scripts for new applications: a designer will have written the quiz that the base level maintainer works with. As such, the designer needs to understand the workings of "Keysearch": this is the individual for whom this document has been written.

The engineer level maintainer is someone who's goal it is to extend or repair the "KEYSEARCH" engine. An engineer would need to be a competent programmer who could read the code for the engine and understand how to modify, compile and link a new version. This will require time and expertise, but should be required very infrequently. The help of an engineer would be needed in the rare circumstance that the base maintainer came up with a new question type that could not be coded by the designer without a new language element being inserted into the engine. An engineer needs to read to code for guidance to its modification. For the most part, the code is well commented and is logcally set out, so no real issues should present themselves.

Using the Software

The manual for the software is the file "keysearch-base.html", which is included in the distribution downloaded with "git". That file can also be found on-line at "http://webdoc.nyumc.org/nyumc/files/mdpp/attachments/keysearch-base.html" ; the on-line version may not be the most up-to-date - sorry about that. Examples of the software in use can be found in the Examples folder in the distribution; some can simply be copied over and used with no modification.

Do not hesitate to contact the author if modifications or enhancements are needed to better suit your requirements.

-eof-