Introduction

Overall Description

Objectives

Timothy is a tool to document an enterprise or activity. The enterprise creates documents and other computer files in the normal course of business. Timothy is the means to organize these documents and explain how they fit together, how they relate to one another, what they contain. The result is a description of the enterprise itself.

Timothy is a management tool that sets out the plans for the enterprise and execution of those plans. It is a management tool that provides access to those critical files people need to complete their tasks.

Functions

Timothy functions as a file storage device organized into a hierarchy of categories. Timothy requires information about each category and document (an entry) that explains each entry, its purpose and relation to the whole (the meta data).

Specific tasks are:

Users

Timothy is used by the managers and workers engaged in the enterprise. Generally all users need access to all three major functions. However, provision is made to just inquiry or download.

Operating Environment

Timothy operates in a networked, multi-user environment. As a world wide web service, The environment may be an intranet or the world wide web itself.

Specific Requirements

External interface

User interfaces

Timothy is a world wide web application available through users Browsers. The basic functionality is the display of lists of files together with their meta data and links which will download the files themselves.

Users traverse the hierarchy of categories through links in the file list. First to the parent category and subsequently to each branch in the current category. Each entry in the list will show the file name, title, author and abstract.

Users can upload documents, create categories and edit meta data through navigation buttons on each page.

Users may search the meta data to find a document.

Hardware Interfaces

Timothy architecture is three separate processes: A web server, a python cgi script and a postgres database. Accordingly, the web services and cgi script are independent of the data base manager and may exist on separate machines. The cgi script may serve multiple database through differing urls.

The user need only use his browser to access the application. Site implementation issues are chosen by site administers and opaque to the user.

Timothy will implement HTML code that is independent of formatting and typesetting issues and will rely on cascading style sheets for appearance. Accordingly, Timothy's pages will be tailored for a wide variety of devices.

Software Interfaces

The basic interface to Timothy is HTTP through a World Wide Web Browser and Web server. Internal interfaces to link the web server to the cgi script, script to dweWebPage and the script to the data base manager are:

1) The Common Gateway Interface for web server to script.

2) dweWebPage is a python library to build HTML pages.

2) SQL from the script to the database manager.

These are well document open standards which allow implementation on a wide variety of platforms.

Testing will be done on a single Linux machine using Apache and Postgresql. In later phases of the project we will develop Mysql as an alternate database engine.

CGI

All Timothy pages will be accessed through a two scripts, manager.py and ldt.py (Look-don't-touch). All of Timothy's functions, except browsing will be called through Buttons on the page prepared by manager.py.

Browsing, performed by both the manager interface (manager.py) and the look-don't-touch interface (ldt.py) is accomplished through hyperlinks for each entry in the category listing.

Thus requests for documents, or categories is described by a URL:

http://servername/DocMgr/manager.py/path/to/node

Forms will be present on each category page with buttons, all named submit. The value of the button, the word in the button, will be used to determine function calls. These functions are;

  1. Root — display the root category of the category tree.
  2. Upload — present a dialog box to upload a file.
  3. Create — create a new category.
  4. Current — display the current category page
  5. Search — search for a word or words.
  6. Edit — Edit the meta data of an entry. An edit button appears with each entry.

Connection information will be stored in hidden fields. These are

  1. hidden_path — Path to the current category
  2. cgi-bin — The path to timothy's web scripts. This data is inserted into each form.
  3. stylesheet — The Cascading style sheet in use. This is a configuration item
  4. template — The page which generated this call to manager.py.
dweWebPage

dweWebPage python library released under the GNU Public License. It provides an API to compile an HTML page.

SQL

Timothy stores all its data in a Postgresql data base. An Entity Relationship Diagram is available with this document. Much of the work of Timothy is performed by plpgsql functions stored in the database.

Functional Requirements

Structure

Timothy displays the contents of a Category which consists of files, sub-categories and one parent. The root of this category tree has itself as a parent. These categories and files are the nodes of a tree.

Each Node has a name and abstract. Files also have an author and a title.

Each category is displayed as a list of its contents with each name a hyper text link.

The CGI script prepares HTML pages from a table of templates. Each template contains the HTML markup and fields (a word enclosed in curly braces) which will be replaced with content from the database.

Timothy uses a library, dweWebPage, which queries the data base for the templates themselves as well as information about the fields contained in the template. Each template field contains the name of a related python object which is instantiated by the library.

The library has methods to populate the fields with data; query the database; and prepare input widgets for display in the user's browser.

Browse

Browsing is the default activity of the site and of the manager script and the only function of the look-don't-touch script. Each node, document or category, is uniquely identified by its path, that is, the list of categories from the root that one must traverse to reach the document with the document's name the last entry on the list.

The Browse function examines the PATH_INFO (entered in the browsers location input box) for the full path to the node. Categories are displayed as a list of nodes in that category. Documents are generally returned with a appropriate mime type. Category listings contain a link to the category's parent so that one may traverse the tree in both directions.

Timothy understands two mime types that must be set by the Edit function (see below). Files of type application/timothy-html will be displayed as part of a Timothy formatted page with the same Heading and Navigation as other Timothy pages. In the same way files of type application/timothy-svg will be inserted as a graphic of type image/svg+xml inside the usual Timothy page.

Each entry on a category page contains a hyperlink to the node. The title, author and abstract are displayed. The manager also provides buttons for editing the entry's meta data and for dropping the entry from the database.

Search

Timothy uses Postresql's tsvector types to store information about full text searches of the title, author and abstract of a node. The search function uses Postresql's tsquery functionality to find documents.

The manager returns a pages similar to a category listing with the results of the search.

Upload

The upload function is a form to return the file to be uploaded, and the file's meta data. If the file exists it, timothy will attached a version numder to the base file name. A second copy of Example.doc will be stored under that name while the original (version 1 of the file) will become ExampleV1.doc

The mime type, which will be returned in the HTTP header when the file is requested, is looked up in a mime type table using the files suffix. The suffix is all those characters after a final period.

Attempts to upload a file with a name existing in the targeted category will create an exception page where the user can select Overwrite or create new version.

Create

The create function is a form to return the path to a new category as well as an abstract for the category. If the category exists, its data is silently overwritten.

Edit

Each category entry may be edited. That is the name, title and other meta changed through a form which displays the current values in a form.

Users change the path to the document to move the document to a new category.

The page allows the user to change the mime type of the file. When originally uploaded this datum was determined from a database table of filee suffices and valid types. A different type (application/timothy-html for example) may be required to meet site requirements.

Drop

Each node may be dropped. That is moved to the superseded category. When called the drop function changes the path to the superseded category and displays an edit page. The user performs the move by clicking on the post button.

Drop tests for duplicate file names and will attached a version suffix to prevent name collisions.

Timothy provides a script, bin/clear_superseded.py, to completely removed the documents in the superseded category.

Configuration

Many items with in Timothy are set in the configuration table and may be changed with the post_config.py script. These items are:

Category
The word to display for each node of the tree.
Document
The word to display for a file in the database.
copyright
The copyright message. This message notifies users about the

rights you have (and retain) in the collection of documents stored in Timothy, not to Timothy itself, which is released under the GNU public license.

database
The name of the <b>Postgres (or PostgreSQL)</b> database.
Brand
The name of the Web site, which appears at the top of each page
cat_icon
The full path to the icon displayed to the left of each subcategory entry on any categories page
doc_icon
The full path to the icon displayed to the left of each document
host
The fully qualified host of Timothy that you use to get to http://[your_webserver_name]/DocMgr/manager.py (that is, your_webserver_name). This must correspond to entries in the timothy-http.conf file.
style sheet
The full path to the cascading style sheet to use in rendering Timothy pages. This may include a cascading stylesheet upload to timothy itself. EG: /timothy/manager.py/path/to/node.css
logo
The full path to the logo displayed at the top of each page in Timothy
superseded
The path to the category where dropped documents and

categories reside.

Use the cgi-script post_config.py ( http://[your_webserver_name]/DocMgr/post_config.py).

Information to make the connection to the database are stored in a text file, /opt/timothy/timothy.conf. This file contains the host, port, database and user names that Timothy needs to connect to the postgres database. The file may contain sections to delineate multiple databases (see multiple databases below) and each section contains name/value pairs. A name/value pair is a line of the form name=value.

name/values pairs are:

host
The name of the machine providing the postgres service.
port
The port where the postgres server listens for a connection.
database
The name of the database with the Timothy data.
user
The name of the role (or user) who owns the database.
password
The password of the user
admin_database
The database to connect to when performing

administrative functions (creating or updating databases.)

creator
The administrative user.
create_password
The password of the administrative user.

Cascading style sheets

Timothy's pages contain four major divisions, header, navigation, content and footer. The id of each <div> tag is set to these values and may serve as a css selector. Placement of these sections on the page as well a appearance should be set in the cascading style sheet.

As the scrips that traverse the category tree use the PATH_INFO to determine what category to display or file to send, a cascading style sheet may be uploaded to timothy and the style sheet configuration item set to that file. EG: /timothy/manager.py/path/to/node.css

Share

The edit page displays a URL to copy and paste into email or other documents. This URL calls retrieve.py rather than manager.py. Administrators can copy retrieve.py to a public cgi directory so that third parties may access specific files with out access to Timothy directly.

Security

Security is implemented through apache and we have prepared a separate guide to security considerations and configuration

Installation

Timothy is distributed as a python library and uses python's distutils. Accordingly, there is a setup.py script in the root of the distribution which administrators use to install the library. This installation route also creates /opt/timothy where various supporting files are stored. Scripts timothy and enter_templates.py are stored in the user's path.

/opt/timothy/bin contains installTimothy.py a script to setup the postgresql database and /opt/timothy contains timothy-http.conf a sample Apache configuration file.

Please refer to /Documentation/manual.html for how to use these scripts to install Timothy.

/opt/timothy/bin also contains timothy_add_docs.sh

Upgrade

/opt/timothy/bin contains updateTimothy.py. This script:

  1. Backs up the current data to /opt/timothy/backups/migrate.sql.
  2. Creates a new database called newdoc.
  3. Populates this database with new versions of the tables, views, functions and triggers.
  4. Imports the backup in migrate.sql created in step one
  5. Renames the existing database to olddoc and the new to docmgr.

Administrative scripts

timothy_shell.py

We provide timothy_shell.py, a command line processor, to query the database, add files and categories, and delete files.

timothy_shell.py defines a subclass to cmd, a python library, that parses and executes commands. Commands are:

dir *path*
print a listing of a category
find *terms*
Search the database for matching terms
get *path*
Get a document from the database
post *category||document*
Create a category or upload a file
drop *path*
Delete a document from the database
select *sql select statement*
Perform a query of the database.

All of these commands may require extensive arguments to work and help messages have been written for each command.

enter_templates.py

dweWebPage, the library we use to prepare each page, stores its templates and field information in the database.

Each page starts as a template with tags, a word in curly braces, that will be replace at run-time. Additionally, information about the tags or fields is also stored in the data base.

dweWebPage defines an abstract class generic_input to represent the fields of a template and a class input_template, derived from generic_input to represent the template itself. The structure of a template may be recursive in that fields of a template may in fact be templates themselves. The library will create instances of various dweWebPage classes and replace the tags with data and return the full content of a page.

clear_superseded.py

Scripts unabashedly deletes the contents of the superseded category with out subsequent recourse.