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

Important News
Introduction
Pre-Installation Guide
Downloads
Upgrade Guide
Installation Guide
Post-Installation Guide
Database Schema
FAQs
Contact Details

Important News

18/04/2002: v0.11 now available

Introduction

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.

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:

COPYING: the full GNU General Public Licence.
ISSUES: a list of known issues in the latest release.
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 System	Browser
Linux	Mozilla 0.7
Linux	Mozilla 0.9
Windows 2000 Professional SP2	Internet Exporer 5.5
Windows 2000 Professional SP2	Netscape 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 System	Web Server	RDBMS	PHP
Free-BSD 4.4	Apache 1.3.23	mySQL 3.23.47	PHP 4.1.1
Linux	Apache 1.3.22	mySQL 4.0 Pre1	PHP 4.0.6
Linux (2.2.16-3smp)	Apache 1.3.14	mySQL 3.22.32	PHP 4.0.6
Linux (2.2.16-22)	Apache 1.3-19	mySQL 3.23.26	PHP 4.0.4pl1
Solaris 7-x86	Apache 1.3-9	mySQL 3.22.25	PHP 4.0.6
Windows 2000 Professional SP1	Apache 1.3-22	mySQL 3.23.32	PHP 4.0.6
Windows 2000 Professional SP1	Xitami v2.4d9	mySQL 3.23.46	PHP 4.1.0
Windows 2000 Professional SP2	Apache 1.3-20	mySQL 3.23.42	PHP 4.0.6
Windows 2000 Professional SP2	Apache 1.3-22	mySQL 3.23.44	PHP 4.0.6
Windows 2000 Professional SP2	IIS 5.0	mySQL 3.23.42	PHP 4.0.6

Downloads

workbench-0.11.tar.gz

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.

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
Search for the register_globals variable and make sure that it is set to off.
Create a text file in your Apache document root (htdocs) called test.php. Add the following line to this file:
<?phpinfo()?>
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.
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
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.
Create the workbench database in mySQL:
mysqladmin create workbench
Move into the workbench directory and import the tables:
cd /usr/local/apache/htdocs/workbench
mysql workbench < sqlscripts/install.sql
Grant permissions to the workbench user in mySQL:
mysql
use workbench;
grant all privileges on workbench.* to workbench@localhost
identified by 'seatonplace' with grant option;
quit
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.
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:
By default there is only one user of the application. The username is 'admin' and the password is 'seatonplace'.

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.

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.
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.
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.
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.
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.
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.
Thats it for post-installation. With all of your Groups, Projects and Users in the system you are ready to start using workbench.
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.

Database Schema

Table	Field	Type	Keys
accessLog	logID	int(6) unsigned NOT NULL auto_increment	PK
	sessionID	varchar(255) NOT NULL default ''
	date	varchar(128) NOT NULL default '
	useragent	varchar(255) NOT NULL default '
	userID	int(6) unsigned NOT NULL default '0'	FK1 -> users.userID
apps	appID	int(6) unsigned NOT NULL auto_increment	PK
	appName	varchar(50) NOT NULL default ''
	appDesc	varchar(50) NOT NULL default ''
	isHidden	enum('Y','N') NOT NULL default 'N'
attachments	attachID	int(6) unsigned NOT NULL auto_increment	PK
	bugID	int(6) NOT NULL default '0'	FK1 -> bugs.bugID
	filename	varchar(255) NOT NULL default ''
bugs	bugID	int(6) unsigned NOT NULL auto_increment	PK
	childOf	int(6) unsigned default NULL	FK1 -> bugs.bugID
	depends	int(6) unsigned default NULL	FK2 -> bugs.bugID
	openDate	varchar(50) NOT NULL default ''
	closeDate	varchar(50) default NULL
	openedBy	varchar(10) NOT NULL default ''
	closedBy	varchar(10) default NULL
	assTo	varchar(10) NOT NULL default ''
	statusID	int(1) NOT NULL default '0'	FK3 -> status.statusID
	typeID	int(1) NOT NULL default '0'	FK4 -> type.typeID
	sevID	int(1) NOT NULL default '0'	FK5 -> severity.sevID
	title	varchar(100) NOT NULL default ''
	description	mediumtext NOT NULL
	resolution	mediumtext
	appID	int(6) NOT NULL default '0'	FK6 ->apps.appID
	versionID	int(6) NOT NULL default '0'	FK7 -> versions.versionID
	targetVer	varchar(6) default NULL
	modID	int(6) NOT NULL default '0'	FK8 -> mods.modID
	screen	varchar(50) NOT NULL default ''
	foundInID	int(2) NOT NULL default '0'	FK9 -> foundIn.foundInID
	history	mediumtext
	dueDate	varchar(10) default NULL
	estimate	varchar(50) default NULL
foundIn	foundInID	int(2) unsigned NOT NULL auto_increment	PK
	foundInName	varchar(20) NOT NULL default ''
	isHidden	enum('Y','N') NOT NULL default 'N'
	foundInDesc	varchar(255) default NULL
groups	groupID	int(6) unsigned NOT NULL auto_increment	PK
	grpAssign	enum('Y','N') NOT NULL default 'N'
	grpName	varchar(50) NOT NULL default ''
	isHidden	enum('Y','N') default 'N'
mods	modID	int(6) unsigned NOT NULL auto_increment	PK
	modName	varchar(50) NOT NULL default ''
	modDesc	varchar(50) NOT NULL default ''
	appID	int(6) NOT NULL default '0'	FK1 -> apps.appID
	isHidden	enum('Y','N') NOT NULL default 'N'
projectAccess	accessID	int(6) unsigned NOT NULL auto_increment	PK
	userID	int(6) unsigned NOT NULL default '0'	FK1 -> users.userID
	appID	int(6) unsigned NOT NULL default '0'	FK2 -> apps.appID
servers	serverID	int(6) unsigned NOT NULL auto_increment	PK
	serverName	varchar(50) NOT NULL default ''
	serverPort	varchar(6) NOT NULL default ''
settings	settingsID	int(6) unsigned NOT NULL auto_increment	PK
	userID	varchar(20) NOT NULL default ''	FK1 -> users.userID
	theFilter	varchar(50) default NULL
	application	varchar(50) default NULL
	status	varchar(50) default NULL
	orderBy	varchar(50) NOT NULL default 'bugID'
	sortWith	varchar(10) NOT NULL default 'asc'
	bgcolour	int(1) default NULL
	emailType	varchar(6) default NULL
	emailOpt	int(1) default NULL
severity	sevID	int(1) unsigned NOT NULL auto_increment	PK
	sevName	varchar(20) NOT NULL default ''
	sevColour	varchar(7) NOT NULL default ''
	isHidden	enum('Y','N') NOT NULL default 'N'
	sevDesc	varchar(255) default NULL
status	statusID	int(1) unsigned NOT NULL auto_increment	PK
	statusName	varchar(20) NOT NULL default ''
	isHidden	enum('Y','N') NOT NULL default 'N'
	statusDesc	varchar(255) default NULL
type	typeID	int(1) unsigned NOT NULL auto_increment	PK
	typeName	varchar(20) NOT NULL default ''
	isHidden	enum('Y','N') NOT NULL default 'N'
	typeDesc	varchar(255) default NULL
users	userID	int(6) unsigned NOT NULL auto_increment	PK
	login	varchar(20) NOT NULL default ''
	fName	varchar(50) NOT NULL default ''
	sName	varchar(50) NOT NULL default ''
	email	varchar(50) NOT NULL default ''
	password	varchar(255) NOT NULL default ''
	grpID	int(6) NOT NULL default '0'	FK1 -> groups.grpID
	lastLogin	varchar(50) NOT NULL default 'Never'
	isHidden	enum('Y','N') NOT NULL default 'N'
versions	versionID	int(1) unsigned NOT NULL auto_increment	PK
	appID	int(6) unsigned NOT NULL default '0'	FK1 -> apps.appID
	version	varchar(6) NOT NULL default ''
	isHidden	enum('Y','N') NOT NULL default 'N'

FAQs

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)

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.