workbench survival guide

the survival guide

Welcome to the workbench survival guide. This document should tell you everything that you need to know about workbench. Use the Introduction if you are considering using workbench or just want to know what the application does. If you have already downloaded workbench try the Pre-Installation, Installation, and Post-Installation Guides. If all else fails you can try the FAQs or Contact details.

This document applies to workbench v0.11 and was released on 18 April 2002


  1. Important News
  2. Introduction
  3. Pre-Installation Guide
  5. Upgrade Guide
  6. Installation Guide
  7. Post-Installation Guide
  8. Database Schema
  9. FAQs
  10. Contact Details

Important News

  • 18/04/2002: v0.11 now available

Back to Top


workbench is a web-based application for tracking bugs and other issues commonly encountered in software development projects. A default installation of workbench will separate these issues into four groups: bugs, change requests, enhancements and tasks. A single instance of workbench can support multiple users, divided into multiple groups (eg Administrators, Managers, Developers, Testers) each with access to specific projects.

workbench was designed to be compatible with the Apache webserver, mySQL relational database management system and PHP server-side scripting language. These applications are available for a number of different Operating Systems and consequently workbench should work in all instances where these applications are supported.

workbench is distributed under the terms of the GNU General Public Licence. If you are unsure about exactly what this licence permits you will need to read the full terms and conditions.

Back to Top

Pre-Installation Guide

Before you install any version of workbench you must familiarise yourself with a number of files which are distributed with the application. If any of the following files are missing from your version you have a copy of the application which is being distributed in violation of the Licence. If this is the case destroy your copy and download the latest version from the workbench project page. You may also wish to report the violation to the author. The files concerned are:

  1. COPYING: the full GNU General Public Licence.
  2. ISSUES: a list of known issues in the latest release.
  3. INSTALL: a plain text version of the Installation Guide below.

workbench was originally designed and tested with Microsoft Internet Explorer on Microsoft Windows 2000. This is of course a ridiculous way to go about developing a web application but from the outset I did not want to be restricted by flaky Document Object Models and poor support for Cascading Style Sheets. The result of this is the following table which shows the only Platform/Browser combinations where I have seen workbench working well.

Operating SystemBrowser
LinuxMozilla 0.7
LinuxMozilla 0.9
Windows 2000 Professional SP2Internet Exporer 5.5
Windows 2000 Professional SP2Netscape 6.01

workbench has only been tested with a small number of Operating System/Application combinations. If you cannot see your system in the following list don't panic, chances are it will be fine, but please let me know so that the list can grow and help other people.

Operating SystemWeb ServerRDBMSPHP
Free-BSD 4.4Apache 1.3.23mySQL 3.23.47PHP 4.1.1
LinuxApache 1.3.22mySQL 4.0 Pre1PHP 4.0.6
Linux (2.2.16-3smp)Apache 1.3.14mySQL 3.22.32PHP 4.0.6
Linux (2.2.16-22)Apache 1.3-19mySQL 3.23.26PHP 4.0.4pl1
Solaris 7-x86 Apache 1.3-9mySQL 3.22.25PHP 4.0.6
Windows 2000 Professional SP1Apache 1.3-22mySQL 3.23.32PHP 4.0.6
Windows 2000 Professional SP1Xitami v2.4d9mySQL 3.23.46PHP 4.1.0
Windows 2000 Professional SP2Apache 1.3-20mySQL 3.23.42PHP 4.0.6
Windows 2000 Professional SP2Apache 1.3-22mySQL 3.23.44PHP 4.0.6
Windows 2000 Professional SP2IIS 5.0mySQL 3.23.42PHP 4.0.6

Back to Top


Back to Top

Upgrade Guide

If you are upgrading from a pre-0.11 version of workbench please read the following notes. workbench v0.11 has no major database schema changes from v0.10. However it is strongly recommended that you use the supplied install.sql or upgrade.sql files on any existing workbench database. These files fix some minor bugs with field sizes in the database. You should always back up any existing workbench database when upgrading.

workbench will now run with register_globals turned off. The folks at PHP strongly recommend that you set this variable to off in your php.ini file. This will give improved security and performance.

Installation Guide

In order to complete the following installation steps you will need to have the correct Permissions to modify your Apache and PHP configurations. You will also need to create a database and import data into mySQL. If you don't have root access on a UNIX machine or Administrator privileges on a Windows machine you need to check your privileges with your Sys. Admin. before you start following these steps.

  1. Open your PHP configuration file (php.ini) in a text editor. Search against the following values and check that are set correctly for your installation: extension_dir, doc_root and session.save_path
  2. Search for the register_globals variable and make sure that it is set to off.
  3. Create a text file in your Apache document root (htdocs) called test.php. Add the following line to this file:
    Start the server and try to view this file in your web browser. eg http://localhost/test.php. You should a detailed description of your servers PHP configuration.
  4. Unpack the tar ball using the following command:
    tar xvzf workbench-x.x.tar.gz
    If you are using Windows you can unpack the archive using WinZip or something similar. This will create a directory called workbench-x.x containing the entire application. Rename the directory to workbench
  5. Move this directory to the Apache documents directory:
    mv workbench/ /usr/local/apache/htdocs
    I'm not going to explain how to do this with Windows.
  6. Create the workbench database in mySQL:
    mysqladmin create workbench
  7. Move into the workbench directory and import the tables:
    cd /usr/local/apache/htdocs/workbench
    mysql workbench < sqlscripts/install.sql
  8. Grant permissions to the workbench user in mySQL:
    use workbench;
    grant all privileges on workbench.* to workbench@localhost
    identified by 'seatonplace' with grant option;
  9. Open config.php in your favourite text editor. Set all of the Global Variables in Section 1. $relative is the workbench root directory relative to your Apache document root. $root is the absolute Apache document root. $path is the absolute workbench root directory. $uploads is the absolute directory where you want attachments and uploads to be stored. For example:
    $root = "C:\Program Files\Apache Group\Apache\htdocs";
    $root = "/usr/local/apache/htdocs";
    $dbserver is the name of the database server. If this is the same machine that is running the webserver leave it as localhost. $dbname is the name of the database that workbench uses. You don't need to change this value. $dbuser is the name of the user that we granted permissions to above. $dbpass is the password we used with the grant above.
  10. Type in the URL, cross your fingers and shut your eyes and there is a small chance that it might work. You should a screen something like the one below:
    Login Box
  11. By default there is only one user of the application. The username is 'admin' and the password is 'seatonplace'.

Back to Top

Post-Installation Guide

This section of the Survival Guide is intended for Administrators or anyone who has just got through the Installation Guide. The steps which follow explain how to do some basic pre-requisite tasks such as creating users and projects.

  1. The first thing you need to do is customise the Administrators account. Find the "My Details" option on the navigation bar and click it. Here you can enter your first name, surname, email address and click the Submit button.
  2. Since every Administrator starts off with the same password this is the next thing to change. Find the "My Password" option on navigation bar and click it. Here you can enter the old password and the new one (twice to confirm). When you click Submit the system will then log you out.
  3. After logging back in find the "Group Admin" option on the navigation bar and click it. Review the default list of Groups that have been created to see if they meet your requirements. On this screen you can create new groups and hide or edit exisiting groups.
  4. When you are happy with the Groups find the "Project Admin" option on the navigation bar and click it. By default a single project exists for this application. Use this screen to create a new project. Once created you can then create versions and modules which will belong to the project.
  5. Next find the "User Admin" option on the navigation bar and click it. By default there is only the Administrators account present. You can create new users on this screen and then configure which Group they belong to. You can also decide which Projects each user has access to.
  6. The next settings screen is called "Issue Admin". This screen allows you to configure the Status, Type, Severity and Found In tables. For example you can add, edit and hide the default fields in all of these tables until they meet your own requirements. The Description field in each table is displayed on the Help page. It is good practice to fill in these values as it will help your users understand the application.
  7. Thats it for post-installation. With all of your Groups, Projects and Users in the system you are ready to start using workbench.
  8. A quick mention of the "Settings" screen. All users have access to this screen and the Administrator will no doubt want to customise a few things. You can currently choose a number of filter options here which apply to how issues are displayed on the "View Issues" screen. You can also decide whether to use full, partial or no background colours on this screen. These colours are derived from the Severity table and are a useful indication of issue severity. Finally you can choose to receive notification emails as plain text or HTML.

Back to Top

Database Schema

accessLoglogIDint(6) unsigned NOT NULL auto_incrementPK
sessionIDvarchar(255) NOT NULL default '' 
datevarchar(128) NOT NULL default ' 
useragentvarchar(255) NOT NULL default ' 
userIDint(6) unsigned NOT NULL default '0'FK1 -> users.userID
appsappIDint(6) unsigned NOT NULL auto_incrementPK
appNamevarchar(50) NOT NULL default '' 
appDescvarchar(50) NOT NULL default '' 
isHiddenenum('Y','N') NOT NULL default 'N' 
attachmentsattachIDint(6) unsigned NOT NULL auto_incrementPK
bugIDint(6) NOT NULL default '0'FK1 -> bugs.bugID
filenamevarchar(255) NOT NULL default '' 
bugsbugIDint(6) unsigned NOT NULL auto_incrementPK
childOfint(6) unsigned default NULLFK1 -> bugs.bugID
dependsint(6) unsigned default NULLFK2 -> bugs.bugID
openDatevarchar(50) NOT NULL default '' 
closeDatevarchar(50) default NULL 
openedByvarchar(10) NOT NULL default '' 
closedByvarchar(10) default NULL 
assTovarchar(10) NOT NULL default '' 
statusID int(1) NOT NULL default '0'FK3 -> status.statusID
typeIDint(1) NOT NULL default '0'FK4 -> type.typeID
sevIDint(1) NOT NULL default '0'FK5 -> severity.sevID
titlevarchar(100) NOT NULL default '' 
descriptionmediumtext NOT NULL 
appIDint(6) NOT NULL default '0'FK6 ->apps.appID
versionIDint(6) NOT NULL default '0'FK7 -> versions.versionID
targetVervarchar(6) default NULL 
modIDint(6) NOT NULL default '0'FK8 -> mods.modID
screenvarchar(50) NOT NULL default '' 
foundInIDint(2) NOT NULL default '0'FK9 -> foundIn.foundInID
dueDatevarchar(10) default NULL 
estimatevarchar(50) default NULL 
foundInfoundInIDint(2) unsigned NOT NULL auto_incrementPK
foundInNamevarchar(20) NOT NULL default '' 
isHiddenenum('Y','N') NOT NULL default 'N' 
foundInDescvarchar(255) default NULL 
groupsgroupIDint(6) unsigned NOT NULL auto_incrementPK
grpAssignenum('Y','N') NOT NULL default 'N' 
grpNamevarchar(50) NOT NULL default '' 
isHiddenenum('Y','N') default 'N' 
modsmodIDint(6) unsigned NOT NULL auto_incrementPK
modNamevarchar(50) NOT NULL default '' 
modDescvarchar(50) NOT NULL default '' 
appIDint(6) NOT NULL default '0'FK1 -> apps.appID
isHiddenenum('Y','N') NOT NULL default 'N' 
projectAccessaccessIDint(6) unsigned NOT NULL auto_incrementPK
userIDint(6) unsigned NOT NULL default '0'FK1 -> users.userID
appIDint(6) unsigned NOT NULL default '0'FK2 -> apps.appID
serversserverIDint(6) unsigned NOT NULL auto_incrementPK
serverNamevarchar(50) NOT NULL default '' 
serverPortvarchar(6) NOT NULL default '' 
settingssettingsIDint(6) unsigned NOT NULL auto_incrementPK
userIDvarchar(20) NOT NULL default ''FK1 -> users.userID
theFiltervarchar(50) default NULL 
applicationvarchar(50) default NULL 
statusvarchar(50) default NULL 
orderByvarchar(50) NOT NULL default 'bugID' 
sortWithvarchar(10) NOT NULL default 'asc' 
bgcolourint(1) default NULL 
emailTypevarchar(6) default NULL 
emailOptint(1) default NULL 
severitysevIDint(1) unsigned NOT NULL auto_incrementPK
sevNamevarchar(20) NOT NULL default '' 
sevColourvarchar(7) NOT NULL default '' 
isHiddenenum('Y','N') NOT NULL default 'N' 
sevDescvarchar(255) default NULL 
statusstatusIDint(1) unsigned NOT NULL auto_incrementPK
statusNamevarchar(20) NOT NULL default '' 
isHiddenenum('Y','N') NOT NULL default 'N' 
statusDescvarchar(255) default NULL 
typetypeIDint(1) unsigned NOT NULL auto_incrementPK
typeNamevarchar(20) NOT NULL default '' 
isHiddenenum('Y','N') NOT NULL default 'N' 
typeDescvarchar(255) default NULL 
usersuserIDint(6) unsigned NOT NULL auto_incrementPK
loginvarchar(20) NOT NULL default '' 
fNamevarchar(50) NOT NULL default '' 
sNamevarchar(50) NOT NULL default '' 
emailvarchar(50) NOT NULL default '' 
passwordvarchar(255) NOT NULL default '' 
grpIDint(6) NOT NULL default '0'FK1 -> groups.grpID
lastLoginvarchar(50) NOT NULL default 'Never' 
isHiddenenum('Y','N') NOT NULL default 'N' 
versionsversionIDint(1) unsigned NOT NULL auto_incrementPK
appIDint(6) unsigned NOT NULL default '0'FK1 -> apps.appID
versionvarchar(6) NOT NULL default '' 
isHiddenenum('Y','N') NOT NULL default 'N' 

Back to Top


  1. When I try to login I just get a blank page, or a No Session message.

1. When I try to login I just get a blank page, or a No Session message.
There are several possible causes for this problem. If you installed Apache and PHP as RPMs on Linux check if PHP was incorrectly configured with the "--without-mysql" option. You must configure PHP with the "--with-mysql" option. If you are using Windows, or if this does not solve the problem check your PHP configuration file (php.ini) for the following:

  • Session.cookie_path should be set to /
  • extension_dir should be set to the directory where PHP is installed. (eg c:\php or /usr/local/php)
  • doc_root should be set the Apache document root. (eg c:\Apache Group\Apache\htdocs or /usr/local/apache/htdocs)
  • session.save_path should be set to a valid directory where PHP can write session files (eg c:\winnt\temp or /tmp)

Back to Top

Contact Details

Before contacting the author directly please check the forums and trackers on the workbench project page. These facilities may prove to be a better arena for communication. If this is not suitable you can contact the author directly by email.

Back to Top

SourceForge Logo Valid XHTML 1.0! Valid CSS!