Anyone involved with meeting tight deadlines quickly realizes the power of ColdFusion. When my marketing organization asked me (Leon) to create a system to assist in revision control for new-product launch materials around the world, I wasn't given much time to do it. Getting large numbers of documents from diverse geographic locations to everyone involved in a product launch concerns any corporation whose business is global in nature. One of the main problems in developing such a system is the ramp-up time required to obtain the necessary tools and skills, particularly if this involves learning a new language.

My experience as a Web programmer prompted my management to request that I obtain all documents from the parties involved in the launch process, open and save the documents in Office 95 format and FTP the files to our server. I then had to code an HTML page to point to the individual files. As we all know, this process is an exercise in futility. After notifying all locations of the "hidden" URL, I'd begin accepting documents and posting them to the URL. It didn't take much time to realize I was connected at the hip to this "little" maintenance job (which, incidentally, I wanted no part of).

I decided there had to be a better way. Although I have over 20 years of coding experience, I'd never coded in a GUI environment. Nevertheless, I was quite aware of what could be accomplished. Since laziness is the mother of invention (maybe a few of you can relate to this), I sat down and analyzed the situation, then drew up a spec on how this revision control system could be automated. Clearly I had to remove myself from the constant updating and refreshing of information.

With spec in hand I went to a colleague and asked if he could create a prototype CGI PERL script within a day or so. I was virtually laughed out of the office. At this time Rob, a young contractor working in my organization suggested a product called ColdFusion. We discussed the spec - a secure area that only authorized individuals could access; and the need to upload data from an individual's desktop, automatically e-mail associates with a detailed comment and create an area with revision history. Rob researched ColdFusion, then came back to me the next day and said it was all possible. We picked up a copy of ColdFusion Server that evening and Rob had a prototype together in a matter of a few days. I was excited; we'd found a tool to implement my spec and I was saved from this never-ending, tied-to-the-hip task. Life was good. I could now turn this project around in a very short period of time and get on with my other duties.

After a week we were making significant progress and were able to demo the prototype to management on Friday. Management liked what they saw and agreed to fund the development as long as it could be accomplished in one month. A month? Ha! With Rob here and my ability to nudge a little extra effort, there was no problem.

Come Monday morning we were ready to really attack this project. Rob arrived, got his coffee and proceeded to give notice. Aargh! Now what? I certainly wasn't going to have time to implement this, along with all my other duties. After a short search, I found George Pandapas, a ColdFusion expert, and the rest, as they say, is history. In the course of the next couple of weeks, the system was functioning in a basic operational manner and by the end of the third month, we had something appropriately named for its acronym: W.I.N., or Workstation Information Network.

W.I.N. - What Is It?
The Workstation Information Network is an automated revision control system designed to organize, store, authenticate and distribute the most recent documents and files pertaining to workstation products. The system provides a simple, effective, automated, worldwide, Web-based system that's available to appropriate workstation personnel. Before W.I.N., revision control was manual and chaotic. With the new system, the workstation team has access to the most recent documentation immediately after the person in charge of content creation has uploaded it. Various documents are neatly organized and centrally located. W.I.N. is dynamic and reflects changes immediately.

W.I.N. was designed to assist in maintaining revision control for projects such as new product announcements and as a nondisclosure information repository. It allows authorized personnel to access the databases specific to the projects they're assigned to, and to view, update and upload new documents into the database. The system generates automatic e-mail to all participants of a specific project with information pertaining to the nature of the uploaded file and with a comment supplied by the individual who uploaded it. It's Web-based and easy to use. It enables a review of draft and final versions of documents, and is password-protected to safeguard sensitive information.

What Are Its Benefits?
If you're a content creator or provider for the workstation business, W.I.N. will ensure that others are aware of the most up-to-date version of your document. It replaces the need to e-mail large files to a host of individuals who need to have the information. It enables you to easily distribute your drafts for review to the appropriate areas and all Product Marketing and Development (PM&D) members, resulting in worldwide immediate access to updated documents. The system, if used as designed, ensures that your content is up to date with the most current data, since you'll be notified of up-to-the-minute changes.

Who Is the Audience?
The audience consists of content creators for the workstation business, primarily residing in PM&D. Other users are area marketing personnel and sales team members. If you're in an area, W.I.N. notifies you of the availability of draft and final documents. It facilitates your review of the document before it's final, and allows you to access the latest versions. You can download, localize and repost information locally on your server, or regionalize the information for your area. Other PM&D members can benefit from W.I.N. by receiving final documents faster than before.

What's the Learning Curve?
A user is virtually an expert after one login. W.I.N. has been designed to be user-friendly, and is functional in its simplicity. The main page used to enter the site acts as an introduction. From this page you can access the W.I.N. online instructions or guidelines, and move to the login screen in order to enter the site. All navigation options are presented via buttons at the top of the screen, under the W.I.N title banner.

Initially you'll be prompted to create a unique password, between six and 12 characters long, to enter the site. (Keep in mind that an administrator will never ask you for your password. Don't share it with anyone.) From the login screen you fill in your username and password in the appropriately marked fields, and press the submit button. You have the option of changing your password for this page at any time.

If you enter the wrong password, you'll be presented with the authentication failed screen, which is coded to direct the user back to the login screen via a meta refresh statement in the HTML code.

Upon successful login, you'll be asked to select the project you'd like to work on, if you're registered for more than one. After your project is determined you'll be transferred to the main, "spreadsheet" page (see Figure 1).

The main W.I.N. page lists the documents for a specific project. The document name is linked to the actual document file, and you can view/download it clicking on the link. The author's name is also linked. By clicking on this link you can send a comment to the author via e-mail. The status column contains pull-down menus listing whether the most recent document is a draft or final version. The document's author can change the version via a pull-down menu. The status pull-down menu appears for all documents for which you're the author.

This routine has probably the most complex SQL statement in the system. The first task is to retrieve the latest version of each document in the currently selected project using a subquery involving the "revision" field, as noted below. Next the document and author tables are joined to obtain the appropriate author information, except in the case of the "ARCHIVE" project, which we use to logically delete or deactivate documents that may be reactivated later. In the latter case we had to dynamically alter the WHERE clause to prevent the "disappearance" of archived documents because no authors are registered in this project. Next, we provide a sort by column feature by dynamically altering the ORDER BY clause, with an additional toggling effect achieved by checking the Client variable list for the column's sort parameter and reversing its sign if found (see Listing 1).

The spreadsheet page displays important information for each document. The first 30 characters of the comments associated with each document are displayed. Each comment is hyperlinked so that if it exceeds 30 characters it can be clicked to reveal the entire comment in a JavaScript- generated window. The revision history button will take you to the Revision History Page. The Date column displays the creation date in European format for its associated document. This is not necessarily the date the document was uploaded, but rather the date the document was originally created. The Revision column displays the document's latest version number, and the Size column displays the size of the document. Other visual features include highlighted rows for documents less than two days old and column headings that repeat every 10 rows so users always know what they're viewing as they scroll vertically.

You display the revision history page by clicking on the revision history button on the W.I.N. spreadsheet page. This page displays information for all drafts of the document you selected. The only difference between this page and the spreadsheet page is that you can't view or download the document. The intent is to review the progression of the document by examining the comments for each version.

The document upload form (see Figure 2) is used to upload documents to a predetermined location on the server's file system. The "Browse" button is included so users can conveniently locate the file on their local system. Clicking this button displays users' folders and files in a manner similar to the Windows Explorer interface, and permits them to click through the hierarchy of folders until they have located their document file. Once located, they upload it by simply selecting it and clicking the "Open" button on the navigation window. The browse window will then close and the file's path will be displayed in the "File To Upload" text field. The "Document Name" field contains a descriptive title associated with the file, which will appear on the W.I.N spreadsheet page. When uploading a revision of an existing document, the user must use the file name used previously. To assist in this task, there's a list of document and associated file names on the right. This is a variable-length list with a maximum length of 10 rows (to stay within the dimensions of the HTML table). Listing 2 provides the code to generate this list.

The document upload acknowledgment page offers a summary of the document just uploaded. If the document file was already on the server, it's been overwritten by the new version you just submitted. The summary page template also sends e-mail to everyone on the distribution list associated with the project.

Additionally, this template handles duplicate file name conditions by continually prompting you to rename your file until it becomes unique. This condition occurs when you attempt to upload a file with the same name as a preexisting file owned by another user. Since you're not the owner of the existing file, W.I.N. won't permit you to overwrite it as a document revision. From this page you have the option to navigate back to the W.I.N. page, which will now display all the information for the new document you just uploaded.

Administration of W.I.N.
The W.I.N. administrator is responsible for ensuring that all users are added to the appropriate projects, and that their registration information is properly maintained. In addition to user administration, the administrator may create, change and delete projects. The administrator also has sole access to the following buttons on the W.I.N. spreadsheet page: Administration for entering the administration area, Change for modifying document information, Delete for deleting documents and Move for transferring documents to other projects, including the reserved "ARCHIVE" project for temporarily "deactivating" certain documents.

From the Administration screen you can add, change or delete a single user, multiple users and projects. You can copy users from one project to another. You can list all users either in one project or in the entire system, and subsequently print these listings. You can turn everyone's e-mail off or on, and you can edit the author table record by record.

To add a user, select a project and click on the Single User Add button (see Figure 3). The project you selected will be highlighted in a list of all W.I.N. projects. You may change this selection and/or select additional projects.

Enter the user's first and last names, hit the Tab or Enter key, or click in another field to autogenerate the username, password and e-mail address values. Edit these values as necessary. Select a User Type and an E-mail Notification Level. Click on the Add button to add the user to the selected project.

For purposes of discussion, a uniquely defined W.I.N. user is someone who has a unique real name ("John Smith") and W.I.N. username ("smith") combination. Thus a W.I.N. project can contain two or more users with the same full name as long as their W.I.N. username is different.

If you select more than one project and the username you enter is already in use, you'll be asked to try another username. However, if you select a single project and someone with the same name and username already exists in that project, you'll be asked to cancel the Add request if this is the same person, or have W.I.N. generate a unique username if this is a different person.

If you're adding a user with the same last name but different first name as an existing W.I.N. user, you may get a username conflict since the initial, autogenerated username is the user's last name. If this happens, you'll be asked if you want W.I.N. to generate a unique username for the new user, or if you want to cancel the Add request.

If the user you're adding already belongs to one or more other W.I.N. projects, their existing password and e-mail address, plus their user type and e-mail notification values, will overwrite the values entered in these fields. So don't bother editing these values when you're adding an existing W.I.N. user to a new project, because they'll be overwritten by W.I.N. anyway. If you need to change one or more of these values, you may do so in a subsequent Change request.

If the user you're adding is a first-time W.I.N. user, the Add command will trigger an e-mail welcome message that explains the W.I.N. system and provides the new user with a W.I.N. username and password, which are initially the same. .The user that already belongs to one or more W.I.N. projects won't receive a welcome message.

The default user type, User, can view all document versions in their assigned project, and can upload and change the status of their own documents. The Read Only user type can view all document versions but can't upload documents to W.I.N. The Field Rep user type can view final document versions only, but can't upload documents to W.I.N. or see any NonDisclosure documents identified as NDA. The Admin user type can move and delete documents; change the status of any document; and add, change and delete users and projects to W.I.N., along with other administrative functions.

If the e-mail notification level is set to "Send mail for revisions," the user is notified whenever a new or revised document is uploaded to the project. If the level is set to "Send mail for revisions and status changes," the user is also notified whenever the status of a document changes (from "Draft" to "Final" or from "Final" back to "Draft"). If the level is set to "Never send mail," the user won't receive any W.I.N.-generated e-mail except for the initial welcome message if they're a new W.I.N. user.

The Single User change command looks similar to the Single User Add.
To change a W.I.N. user's registration information:

Use the List Users command to list users who already don't receive e-mail notifications, so you'll know whom to turn off when you turn all e-mail back on.

To facilitate database maintenance, the system is designed with a browse and update facility for the Author and Document tables. You can access the Author table by clicking the "Browse & Update" button on the administration screen. This displays the entire record, including fields reserved for future use. You can go to the first, previous, next or last record in the Author table by clicking the appropriate navigation button.

Invoking the routine for browsing and updating the Author table required a little programming finesse that combined ColdFusion and JavaScript capabilities in some interesting ways. First, we found it necessary to use JavaScript to escape the frame we were in so we'd have a full window in which to display our record data and related controls. Generally, this is accomplished by specifying a TARGET attribute with a value of "_top". However, ColdFusion's <CFLOCATION> tag doesn't support this attribute, so using this tag would confine our template output to the right-hand frame of the admin frameset.

For the "previous" and "next" buttons this involves decrementing or incrementing the ordinal of the previous record number to find the new record number. The final key step is to specify this value for the STARTROW attribute in the <CFOUTPUT> tag, and to be sure to limit output to only one record by setting the MAXROWS attribute to one (see Listing 4).

The administrator is the only person allowed to delete a document. This normally occurs as the result of an e-mail request from a user who has erroneously uploaded a document, or it may be that a document is simply outdated and needs to be deleted. By clicking on the Delete button for a specific document listed on the spreadsheet page, you may physically delete the record from the database

As mentioned earlier, W.I.N. documents can be moved from project to project. New users will generally use a generic project to begin their work, and as projects are defined they will identify which documents actually belong in different projects. Transferring these documents to their designated projects is the primary reason for having the Move command. It's also used by the administrator for storing requested deletions in a holding area ("ARCHIVE") in the event that the document and the history need to be reviewed in the future.

Published May. 6, 1999 — Reads 6,748
Copyright © 2008 SYS-CON Media. All Rights Reserved.

Related Links

▪ Figure 1

▪ Figure 2

▪ Figure 3

▪ Figure 4

▪ Source Code

About Leon Eno
Leon Eno, who currently works for Compaq Computer in the Workstation Marketing Group, has over 20 years of proactive experience in information technology. His special focus is on developing and supporting sales/marketing and financial systems. Leon also freelances in the areas of Web graphics, prepress processing and Web design and programming. Leon can be reached at leno@cvsi.com