Table of Contents

• Introduction
• System Requirements
  
  • Client
  • Server
• Software Installation - Webserver
• Software Installation - Command line / Email
• Post Installation Configuration
• Keystone Basics
• Working with Keystone
• Appendix A - Glossary
• Appendix B - Writing Reports
• Appendix C - Keystone Internals

Section 1 - Introduction

Keystone is a web-based application designed to help a workgroup keep track of issues and tasks via a shared central resource. The system was designed specifically with the IT department in mind, where quick access to shared data and history is a requirement, both from a internal organizational perspective, as well as the needs to keep the customers happy.

Keystone accomplishes these goals via several mechanisms.

One, all the data is stored on the server, in a SQL database. This makes data retrieval very fast, and, because the mechanism for data storage and retrieval is a standard (well supported SQL servers), the data can be made accessible to other applications, such as scripts, desktop applications, etc.

Second, the only requirement for accessing the data is a web browser. No local software needs to be installed on the client. The web browser does not need to be high end, either. It simply needs to be able to support forms, tables, and cookies, which virtually every browser available today does. No frames, no java, no javascript, no activeX components, no DLL hassles.

To access the Keystone system, you must have:

• TCP/IP connectivity to the web server hosting he Keystone web pages.
• A web browser capable of supporting HTML tables, forms, and cookies (Netscape 2.0 or later, MS Internet Explorer 2.0 or later, Opera 3.0 or later, Mosaic, etc)
• Cookies enabled in your browser (NOTE - this is NOT a security or privacy risk, despite the hype on the Internet. Cookies are a privacy risk only when misused, to collect information on your Internet usage without you knowing it. Keystone uses cookies to verify your identity every time you access one of the web pages, in order to keep your private settings correct, etc. If your browser supports cookies on a site-by-site basis, enable cookies simply for the site hosting your Keystone system.)

To host a Keystone installation, you must have:

• A webserver available to the users who will be accessing your system. Keystone has been primarily tested using Apache (available at http://www.apache.org), but other web servers will work (Netscape Commerce Server, Microsoft's IIS, etc).
• Full access to the server that will be hosting the pages. The installation requires the installation of several system-level programs, as well as possible configuration changes to a running web server. On Unix platforms, root access is pretty much required for the installation. Once the software is installed, it can be maintained remotely by the Keystone administrator, without requiring root access on the server for updates / maintenance.
• The PHP3 server parser. All of Keystone is written in PHP3, a very powerful scripting language for web servers. It is available at http://www.php.net. For best performance, it is recommended that PHP be installed with Apache, compiled in as an apache module.
• A database resource. Keystone requires a SQL server for storing all its internal data. We highly recommend MySQL, available at http://www.tcx.se. It is a very fast and portable SQL server which includes support for many platforms and configurations, as well as client support such as Perl libraries for script access, command line access, and ODBC drivers for Windows users. Support is also available for PostgreSQL, available at http://www.postgres.org.

Keystone unpacks (see below) into several directories:

	./keystone		The .php3 files that make up Keystone
	  >--conf		Configuration files
	  >--docs		These documents
	  >--struct		Database structures
	  >--graphics		Graphics needed for the app
	  >--support		Various support utilities
	  >--perl		Perl utilities
	    >--templates	Templates for Keystone.pm

Installation

Keystone is distributed as a single .tar.gz file. It should be unpacked in the directory -above- where it will be run from, since it creates it's own directory structure when unpacked.
1. cd to the directory where your HTML pages for your web server reside.

   	cd /usr/local/www/data

2. Unpack the distribution

   	gunzip -c keystone-xxx.tar.gz | tar xvf - 

   Make sure the directory structure described above is created, and all files are dropped in place. the 'root' Keystone directory should have a bunch of .php3 files, the 'struct' directory will have files such as 'slips.mysql', etc. This file (INSTALL) should be in the 'docs' subdirectory.

3. Copy the 'keystone.conf.default' file to 'keystone.conf'. Edit the file 'keystone.conf', and make any configuration changes you want. This file will hold your localized customizations. Future upgrades and updates will not overwrite this file.

   *IMPORTANT STEP*. The keystone.conf.default file has the current version number in it. You should comment out this line in the keystone.conf file you use for localization, or else the system wil always report the wrong version.

   *IMPORTANT SECURITY NOTE*. The configuration file is in a seperate directory (./conf/). This is to allow a system administrator to make the .conf file unreadable from the web should some user type 'http://foo.com/keystone/conf/keystone.conf'. You may want to consider dropping in a .htaccess file to limit access to this directory. Copy the 'colors.conf.default' file to 'colors.conf'. Edit the file 'colors.conf', and make any configuration changes you want. This file will hold your localized color and site layout customizations. Future upgrades and updates will not overwrite this file.

4. Create the database within your database server. Consult your database server documentation for the specific procedure for this. For 'mysql', the command is:

   	mysqladmin create keystone

5. Keystone uses approximately a dozen tables for its data. Each of these tables needs to be created within the system, based on the structures stored in the 'struct' subdirectory.

   These structure files were created using the 'dump' utility many Unix SQL servers come with. To restore a table into the server, simply pass the structure file back into the command line utility.

   For 'MySQL', the command is:

   	mysql keystone < file.mysql

   Do this for all tables for your particular server. Currently, Keystone includes these structure files:

   	*.mysql		MySQL (www.tcx.se)
   	*.pgsql		PostGres (www.postgresql.org)

6. Test your login

   Point your web browser at the path you specified, at the 'index.php3' file. You should see a login screen. If you do not, or get an error, make sure you have PHP3 installed properly.

7. Login!

   The default login is 'admin', and the password is 'abc123'.

NOTE! As of 3/28/1999, the Keystone Perl interface has been replaced and updated. There are new files, new command line options, and other goodies. If you upgrade to Keystone 0.50.03 or later, note that there are significant changes.

Keystone now uses the 'Keystone.pm' library for all command line and email interaction with the system. As of this release, only the email version ('keymail.pl') is included.

keymail.pl is the email integration element of Keystone.pm. It allows Keystone to receive slips via email, as well as allow users to add followups via email.

Note - Setting up the Perl interface to Keystone can be tricky. A good knowledge of systems administration, as well as a working knowledge of Perl is a big help, but is not required.

If you are planning on running the Perl utilities keymail.pl for handling email coming in and out of the system, or to batch process loading slips and other information into the system from the command line, you'll need to configure the Perl components of Keystone.

The following components must be installed in order to use Keystone.pm:

• Perl v5.003 or later.
• Mail::Tools
  This is available from CPAN. Mail::Tools includes all the tools necessary for Keystone.pm to be able to receive, parse, and reply-to email.
• DBD::DBI
  This is a generic database interface, and is the standard way Perl applications talk with databases. It is also available from CPAN, but you'll need to make sure the DBD for your particular database is installed. For MySQL, the DBD::DBI system comes with the distribution, in the 'Perl' subdirectory.
• Text::Template
  This module is available at CPAN and allows you to create a 'template' file, in this case to contain the text of the email that will be sent back to the user, with substituted fields from the database.

Before starting configuration of Keystone.pm, make sure the modules above are installed and operational. A quick test is to cd into the 'perl' directory, under the Keystone installation dir, and type './keymail.pl -h'. If all the modules are installed properly, you will get a help screen for keymail.pl, showing the version of your installation, etc. If not, you'll get an error message similar to this:

	Can't locate Mail/Internet.pm in @INC 
	(@INC contains: /usr/local/lib/perl5/i386-freebsd/5.00404 
		/usr/local/lib/perl5 
		/usr/local/lib/perl5/site_perl/i386-freebsd 
		/usr/local/lib/perl5/site_perl .) at ./keymail.pl line 22.
	BEGIN failed--compilation aborted at ./keymail.pl line 22.

Assuming all the modules are installed, here's a few more errors you may encounter:

	$ ./keymail.pl -h
	keymail: cannot open config file /apache/htdocs/keystone/conf/keystone.conf : No such file or directory

This means that Keystone.pm couldn't find your configuration file for Keystone. By default, it looks for ../conf/keystone.conf. Make sure you are running your utilities from the 'perl' direcotry under where you installed Keystone.

	$ ./keymail.pl -h
	bash: ./keymail.pl: No such file or directory

This indicates that the very first line in keymail.pl, which begins with #!, is not pointing to the correct location for the Perl binary. Edit that line and put in the correct full path. Another approach is to place a symbolic link in to link where you have your Perl binary to the location Keystone is looking for. This is the preferred method, since it allows you to update Keystone later on without having to re-edit this file.

Assuming all goes well, you should get the keymail.pl help screen, defining what some of the command line parameters do, etc. Look to the top line to make sure the version number is correct. It should match the version of Keystone already installed on this server.

Most people interested in using keymail.pl will be most interested in using it to provide and E-Mail gateway into Keystone. This has been the main driving force for developing keymail.pl, and is where it's strengths lie. Further development on the script will make it better suited to real command line interaction, but for now, it works best as a mail handler.

To set up keymail.pl for use as an email gateway, you must have root access on the machine hosting Keystone. Follow these steps to enable keymail.pl as an email handler:
1. Install and configure keymail.pl as documented above.

2. Edit the system aliases file for the server running Keystone. In most systems, this will be in /etc/aliases.

3. Create the following entries

   	keystone:		"|/apache/htdocs/keystone/perl/keymail.pl -mailinfo";
   	keystone-submit:	"|/apache/htdocs/keystone/perl/keymail.pl -newslip -status=O -priority=8";
   	keystone-followup:	"|/apache/htdocs/keystone/perl/keymail.pl -newfollowup -public";
   

   You should change the path to keymail.pl to match your installation

4. Run the system utility 'newaliases' to make sure your aliases file is up to date, and there were no syntax errors.

5. Send mail to 'keystone' on this machine. You should get an automatic reply describing how to submit slips into the system.

Note that you can use various command line options to set up special mail aliases that submit slips in different ways. For instance. Say you have a parent slip # 1210, titled "QA Issues." You'd like to have a special mail alias for folks to submit problems to that would automatically put them under this slip. You could create an alias to do this like this:

	qa:	"|/apache/htdocs/keystone/perl/keymail.pl -newslip -parent=1210"

Note that the opening tech of the ticket will be the person's email address whom emailed the ticket in. If the parameter -currtech is set, it will assign the slip to them. For example, the following alias:

	qa-unix:	"|/apache/htdocs/keystone/perl/keymail.pl -newslip -parent=1211 -curtech=unixadm"

will create a slip, whose parent is # 1211, and it will be assigned to the 'unixadm' user.

Using the above examples, here's how each alias will respond:
• mail to 'keystone' will result in a help message being returned, describing what aliases are available.
• mail to 'keystone-submit' will result in a new slip being generated in the system, and an answer being sent back to the submitter giving the new ticket number, etc.
• mail to 'keystone-followup' will add a new followup to the ticket specified in the subject of the mail message. Note that Slip ID's in the subject lines should be specified as '#nnnn' where 'nnnn' is an active slip in the system.

The responses Keystone.pm uses come from templates stored in the 'keystone/perl/templates' directory. Keystone comes supplied with 5 default templates:

• addfollowup.tmpl.default
  This template is used when sending mail back to a user after they have added a followup via email.
• addslip.tmpl.default
  This template is used when sending mail back to a user after they have added a new slip into the system via email.
• followup.tmpl.default
  When a Keystone.pm utility needs to show a slip that has followups, it uses this template to show each followup in the listing.
• mailinfo.tmpl.default
  This template contains the Help text sent back with the 'mailinfo' parameter.
• showslip.tmpl.default
  Any time a Keystone.pm utility needs to show a slip, either in email or on the screen, it uses this template.

The default templates can be replaced by customized ones. Simply copy the '.tmpl.default' file to just a '.tmpl' file, and edit the new copy. Do not edit the .default files, since the next time you update Keystone, any changes will be overwritten.

If you have successfully logged into your system, there's still several steps to take to get your system ready for department usage. All these functions may be done through the Maintenance menu under Other. See the user documentation (still under construction) for details.
1. Create user accounts.
   Every person using the Keystone system requires a unique login name and password. These accounts are created by the administrator via the 'Maintenance' functions. On the left side of the screen, select the 'Other' menu, then click on "maintenance".

   From the Maintenance screen, click on 'People'. A screen will come up allowing you to add or modify users in the system. Click 'add' to add a new user. The fields are:

   	login		The login ID of the user
   	fullname	The users full name. (last,first is best)
   	passwd		Encrypted password.  Leave blank for now
   	phone		Phone number - freeform
   	email		Email address (user@host.com)
   	grp		What group the user is part of.  Groups
   			can be defined later, the only predefined
   			groups are 'tech' and 'admin'. 
   	company		A company tag.  Currently for information
   			purposes only.

2. Set user passwords
   The passwords are not maintained in the normal 'people' maintenance screen. Use the 'password' function on the Other menu to change passwords. Users in the 'admin' group may change any users password, while other users may only change their own.

   After adding all your users in step 1, make sure you go through and set their passwords.

3. Assign administrator priveleges, and assign technicians.
   Keystone has the capability of 'granting' administration priveleges to a user via the Groups function. Select 'groups' from the Maintenance screen. By default, Keystone has 2 groups defined 'admin' and 'tech', and the 'admin' login is a member of both. Add any other users to the groups as necessary. Usernames go into the 'g_people' column, seperated by spaces.

   The 'g_assign' column specifies whether this group can be used when assigning slips to certain groups.

4. Review the Status codes to see if they match your site's requirements.
   The 'Status' table contains the codes that Keystone uses to tag slips. The only 'required' code is 'C' for Closed. Any other tags may be added here. There is a default list provided in the distribution.

5. Edit the 'master' table and change your sites server key. Keystone uses a server key to encrypt the password stored in your browser between sessions. This should be changed by editing the 'master' table, and clicking 'edit' next to the server key. Any string may be used.

6. Reset the 'admin' password. The 'admin' password in the keystone distribution is the same for all installs. Before making your system publically available, be sure to reset the 'admin' password to something other than the default. To do this, make sure you are logged in as 'admin', and use the 'Password' function on the Other menu. Change the 'Username' field to 'admin', and type a new password in.

The Login Screen

So now you've got Keystone installed, and you can see your first login screen:

This is the start point for any Keystone session. The screen is divided up into 4 sections:

• To look up a specific slip
  Once you have slips entered into your system, users will be able to type in a specific slip ID here, and jump right to the public view of that slip. Note that the slip -must- be marked 'Public' for this to work.
• To view a customers slips
  As of Keystone 0.30.03, this function is not yet active.
• To log in to keystone
  Users with valid accounts within Keystone use this section to log into the system. Type your username into the 'Username' field, your password into the 'Password' field, and click 'Log In'. Assuming all goes well, and your password and account are valid, the main Keystone screen will appear.
• Browse Slips
  Keystone allows users who don't have explicit accounts within the system to browse slips that have been marked as 'public' by the actual folks using Keystone. This button takes a user to the Visitor pages (see below). You do not require a username and a password to access the Visitor pages.

Below is an example main screen. It is currently 'zoomed' in on a specific slip. Note that no matter where you are in Keystone, the 'outer' menus will remain the same, allowing you to jump quickly between functions:

Keystone menus let you view only the options you need. Normally these menus are 'collapsed' - the options underneath them are invisible. To the left of each menu item is a small character, called a Spinner, that shows whether a menu is 'collapsed' or 'expanded'. To "spin" a Spinner, click on it, and it will either show or hide the items below it.

Here's a summary:

Symbol	Definition
	'Collapsed' spinner, meaning there are more items available
	'Expanded' spinner, meaning the item is already expanded, but may be collapsed
	Generally this is used to say "Go back to the beginning"
	View the parent of this item, or, in another parlance "go up a level"
	This generally takes the place of a button when doing a search or the like.

For example, if you've just logged into Keystone, you'll notice the Slips menu is 'Collapsed', and looks like this:

If you click on the 'Expand' spinner, the menu will expand, showing all the sub-options:

Clicking again on the spinner (now pointing down), will collapse the menu again.

Other controls on the standard Keystone screen:

• Version number, Copyright, and current login
  At the very top of the screen, Keystone displays the current version of the software, the copyright notice, and the username of the currently logged in user in square brackets [].
• Jump To...
  If you know the specific slip ID of a slip you'd like to view, you can type the slip number in the Jump To box, and click on the circle (in some browsers, you can just hit after typing the number. Keystone will jump to that specific slip and view it, if it exists.
• Last Result:
  This section of the screen shows the results of the last Keystone operation. It's a good idea to keep an eye on this display to see if the last operation generated an error or if it succeeded.
• QuickSlip...
  A Quickslip is a specific slip designed by your system adminstrator as important enough to warrant it's own section on the screen all the time. It's common to put top level "parent" slips in the Quickslips listing for use as a categorizing mechanism. For instance, you may have a slip in the Quickslips menu titled "User Issues". At any time you can pull down the Quickslips menu, select "User Issues", and click on the circle to the right of it, and Keystone will zoom to that slip, and show all summary information, such as children and followups.
  Quickslips must be defined by the Keystone Administrator.

Working with Slips

• Overview
  Slips are the basic element of all Keystone operations. They can be considered 'ToDo' items, 'tasks' 'tickets', whatever. These are all synonymous.

  To start working with Slips, make sure that Keystone is currently set to display slips. The select arrow next to 'Slips' on the menu bar should be highlighted (it may be pointing right or down).

  In the main display are, you will see the current view of your Slips. This display remains the same even when you go to other views in Keystone, and come back to Slips. In general, it has two display modes:

  • Listing - a current 'view' of slips is displayed, listing each slip in it's own row in a table. This 'view' is customizable under Slips - Properties.
    
  • Zoomed - Keystone is 'zoomed in' on a specific slip, showing detail on that slip, including all it's children, followups, etc.

• Adding a new slip
  Keystone has 2 seperate screens used to add slips into the system; Single Screen and Long

  Single Screen Add
  Click on 'Slips - Add' from the Main Menu. You will see the Single Screen Add New Slips screen:
  

  Summary of fields:
  

  • Child of...
    A slip can have many 'children' slips organized underneath it. This selection allows you to specify which existing slip will be this new slips 'parent'. Generally you would organize slips under a certain Parent to denote tasks pertaining to a specific project, or tasks that make up a certain project. Another way to use the Parent / Child relationship is to use certain parent children as 'Categories', under which you'd place slips within that category. For instance, you might create a Parent slip called "Windows 95 Problems", and another parent slip called "Unix Desktop Problems". That way you could organize your slips under each category as needed.
    Whether or not a slip appears within this pulldown depends on how the specific installation of Keystone is configured. See the appendix on 'keystone.conf' for details.
  • Dependent on...
    You can specify another slip that this slip is 'Dependent on'. The current slip will be marked as "Inactive" until the other slip (the one shown in the "Dependent On" pulldown) is closed, at which this slip will be marked as "Open".
  • Opened by...
    This selection is filled in automatically and cannot be changed. When you add a new slip into the system, it will be tagged as 'opened by' whatever your login name is.
  • Contact...
    This pulldown sets the 'Contact' for the slip. Contacts are managed under the 'Contacts' Main Menu pick. When a Contact is selected from this pulldown, default information from that entry within the Contacts page will be displayed on the slip when it is zoomed.
  • Assigned To...
    A Slip is 'assigned to' a Technician within Keystone. In this way, a Tech can come in and view any slips assigned her, or to anyone for that matter. This pulldown menu is populated with users within the Keystone system who are part of the 'Tech' group. See the Configuration and Maintenance section for details on setting up the Tech group.
  • Status
    All slips have a Status associated with them. This determines the current condition of the slip. Keystone comes preconfigured with several Status codes:
    • U - Unassigned (The slip has yet to be assigned to a technician)
    • A - Active (The slip has been assigned and is currently being worked on)
    • I - Inactive (The slip is 'on hold' for some reason, such as waiting for another task to complete.)
    • O - Open (This is used in the 'Ticket' metaphor. The ticket is in and assigned)
    • C - Closed (The slip is complete or closed)
  • Priority
    Slips may be assigned a 'Priority' to help in organizing what tasks need to be worked on in what order. Priority numbers go from '1' meaning 'Top priority' to '10' meaning 'lowest priority.'
  • Problem
    A one line 'quick description' of the problem.
  • Summary
    A full description of the issue this slip represents. Summaries can be any length.
  • Can this slip be viewed via the public 'View all slips' pages?
    Normally Slips are hidden from the public pages (available from the Login screen). Marking a slip as 'public' on this screen makes this slip available for viewing without requiring a login and a password on Keystone.
  • Send Email Update to...
    Keystone can automatically generate email to users. Simply check which person should receive the email, or type in an email address, and Keystone will generate the mail as soon as the slip is added into the system.

  Long Add
  The Long Add screen was developed specifically for helpdesk operations where the person entering slips into the system may need to look up information along the way, such as finding the customer information, etc, before actually adding the slip in.

  Click on 'Slips - Add (long)' from the Main Menu. You will see the first of the Long Add screens come up:

  

  The Add (Long) screens go in sequence, starting with this page. Across the top of the page is a series of boxes displaying the status of the slip being added. A Grey box indicates the information for this section has not yet been entered. Yellow indicates the current screen, and Green indicates the data has been entered.

  Step 1 of the Long Add is for getting contact information from the customer. The operator can enter in any piece of information in any of the fields, and click 'Find' to do a search on that information. If there is a match, the columns are filled in. Note if there is more than one 'match' to the query, only the first one is shown.

  For example, if the operator is taking a call from a user saying they are from 'Stonekeep Consulting', the operator could simply enter 'stonekeep' in the 'Company' field, and click the 'Find' button to the right. Keystone will search the contacts database for the first record with the word 'Stonekeep' in the Company column, and display that data:

  

  Once the correct contact has been filled in, the operator can click Next to go to the Problem Description screen:

  

  On this screen, the operator can take in the Problem and Summary information for the slip. As before, once data entry is complete for this screen, the operator can just click Next to set the options on the slip:

  

  This screen lets the operator set various options on the slip. These options mirror those on the normal 'add slips' screen, but to summarize:
  

  • Select Status
    These codes are taken from the 'status' table, and are used to label the current status of a slip. Many sites use the Status codes to classify slips, and allow flexible browsing.
  • Select Parent
    The 'parent' slip of the newly created slip.
  • Select Priority
    The priority that should be assigned to the new slip.

  Once all the information has been selected, the operator clicks Next, and the final summary screen comes up:

  

  This screen allows the operator to review the new slip before actually adding it into the system. Once everything is approved, the operator can click Commit and slip is added into the system. A confirmation screen is displayed after the submission, so the operator can note the new Slip ID:

  

• Working more closely with slips : The zoomed slip menu Any slip, once in the system, is now available to be modified, updated, assigned to other slips, and generally worked with. All these functions are available once you zoom in on a slip, (by clicking on it's number in the main view, or by 'Jumping' to it, via the Jump To pick on the menu bar). Once you are zoomed in on a slip, more options become available:

  

  This screen shows all the information on file about a specific slip. There's a lot of information here, so lets break it down, starting with the left hand menu.

  • Up Arrow
    Click on the up arrow here to view the parent of the currently displayed slip.
  • Left Arrow
    Collapse the current slip, and return to the slip summary pages.
  • Slip Number
    The current slip being viewed. If you have 'expanded' a slip, and it's not the only one on the screen, you can click on the slip ID itself, and Keystone will zoom to that slip.
  • Children and Followup counts
    Below the Slip ID is displayed the number of children, and the number of followups associated with this slip. In the above example, there are 93 children, and 20 followups on this slip.
  • Functions menu
    Along the left side are the various functions that can be performed on the currently displayed slip:
    • Add Followup - Adds a followup comment to the slip
    • Add Child - Adds a new slip into the system whose parent is the currently displayed slip.
    • Modify - Edit the current slip. Note that when you modify a slip, Keystone automatically adds followup information describing what changes were made, when, and by whom.
    • Close - Change the status on the current slip to 'Closed', after asking the user for a close message. The status is changed, and a followup is automatically added describing who closed the slip and when, and what reason was given.
    • Delete - Delete a slip from the system. All followup information is deleted as well. Note that deleting a slip with children may result in slips pointing to a non-existent parent slip. It's better to simply mark a slip as "Inactive" in this situation.
  • Email...
    Keystone can generate Email at any point, to any person. These functions are available anytime a slip is added or modified, or can be generated on the fly via this menu pick.

    Clicking on this function brings up the Email dialog window, where you can specify whom to send the email to:

    

    The Email menu has several options on it:

    • Opened by..
      Send email to the user who opened the slip.
    • Contact email..
      Send email to the current contact's email address (set in the Contacts system)
    • Current Tech..
      Send email to whomever this slip is currently assigned to
    • Type in an address.. Send email to an arbitrary address. Note that multiple addresses may be entered here, seperated by spaces.
    • Send only most recent followup
      Normally Keystone generates a mail message that contains all 'public' followups. Selecting this option will limit the mail to just show the most recent followup.

Working with Filters

• Overview
  The Filters system in Keystone allows a user or an administrator to make custom 'views' of the Keystone data. The data can be slips, resources, or contacts.

  WARNING - The Filters system allows you to enter raw SQL commands that will be run against the Keystone database. Since the commands are note full (they require a 'select' clause in front), it is nigh on impossible to actually damage data, but you can end up with MySQL errors coming out of the system if you do a Filter improperly. We suggest you have a working familiarity with SQL and Keystone's internal data structures before you start working with Filters.

• Viewing Filters
  The Filters menu pick is available under the Other options along the left menu. Selecting Filters brings up the main Filter editor window:

  

  This screen will show all the filters that are available. You may add, edit, or delete any filters in the system.

• Modifying Filters
  A Filter consists of 4 pieces of information:
  • To be applied to..
    Which dataset will this filter be appropriate for? The available options are Resources, Slips, or Contacts.
  • Is this filter public?
    Marking a filter as 'public' means that other users can use it when they are logged in to Keystone. Note that there are no permissions involved here. If you make a filter public, any other user may edit or delete it.
  • Description of this Filter
    A line of text describing what this filter does.
  • Select statement
    This field contains the actual SQL command that will be used to view the slips you want. If you're familiar with SQL, what goes here is what normally goes in the 'where' clause of a SQL command.

    Keystone selects slips from the 'slips' table based on a normal SQL command:

    select * from slips where currtech='bob';

    Entering a Filter allows you to change what the 'where' clause will be on your normal slips display.

    Note that you can use the special phrase USERNAME to specify that when the filter is used, Keystone should substitute the current user for the word USERNAME.

    The following screen shows a Filter edit that will show all the slips whose status is 'U' (meaning 'Unassigned') and will order by open date, descending

    

Working with Contacts

• Overview
  The Contacts system in Keystone is used to keep track of individual sites, customers, people, whatever that may be associated with other elements in the system, such as resources, slips, or other contacts.
  

Working with Resources

• Overview
  The Resources system in Keystone is used for tracking inventory and accessories within a department. It can be used for anything from software license inventory to hardware and asset tracking.

  Resources are divided into two categories. Resources and Accessories:

  • a Resource is a single item that is inventories based on a unique identifier, such as an asset tag, serial number, etc. A single Resource entry will always refer to a single unique item. Examples of Resources would be computers, monitors, etc.
    
  • an Accessory refers to a type of item. Accessories are not tracked individually, but are counted as an 'add on' item to a Resource. Examples would be keyboards, cables, software packages (in the situation of a corporate license) etc.

Apache

A high performance publically available webserver. More information on Apache is available at http://www.apache.org. Apache is the suggested server software to use for hosting Keystone.

Child Slip

A slip which has a parent SID set to another slip. See 'Parent Slip' for more information on parent/children relationships in Keystone.

Contact

A person or organization within Keystone used when opening slips. The Contacts function within Keystone allows a user to enter in contact information such as name, address, company, phone extension, etc etc, and have them show up when viewing a slip. For small installations, the Contact could be individual users being supported by the Keystone installation. For larger ones, they could refer to an entire company or an installation. A Keystone user could use the Contact tag on slips to view a list, say, of all open slips for a certain Contact.

Cookie

A piece of information stored within the browser when accessing a web page. Cookies can contain any information, and are frequently used on the Internet to track an individual's use of the Web. Keystone uses a single cookie, stored in the browser, to identify that the user has logged in already - this avoids having to type a username and a password every time they want to hit a web page. Note that there is a general feeling on the Internet that cookies are bad terrible things that should be abolished. Like most technologies, cookies are only bad if they are misused. Keystone uses them for what they were intended for - uniquely identifying users whenever they access a Keystone web page, as opposed to what most people are objecting to - that being using cookies to track general use on the Internet.

Followup

A history entry on a slip. Whenever something happens that is associated to a slip, ranging from changing who the contact is for the slip, through commentary or updates, it is entered as a 'followup' to a slip. Slips can have any number of followups associated with them. The followups provide a complete 'audit trail' or history of what has happened to the slip since it's inception. An example would be a slip opened referring to a problem a user is having with a word processor. After the slip is opened, a dispatcher may reassign the slip to a certain technician. That reassignment would automatically be added as a followup showing who made the change, what was changed, and when. Later, the technician may call the contact on the slip back, and leave a message with some pertinent information. The technician would open the slip, add a followup, and type in a comment such as "called, left a message". In this way, slip history is kept up to date, and anyone looking up information on the slip can find out exactly what has happened when.

Keystone

The general term for all the software components and designs in this package. This includes all the scripts, data structures, documentation, etc.

MySQL

A public domain database server available from http://www.tcx.se. MySQL is the preferred database server software to use with Keystone.

ODBC

Open Data Base Connectivity. This is a definition written by Microsoft for a 'standard' methodology for accessing databases. PHP has support for ODBC resources within it, but the ODBC links for Keystone are just beginning to be written. If you must use an ODBC resource for your data (such as a Microsoft SQL server from an NT server), be prepared to do some work.

example, a project may be to be bringing up a new server. This project may consist of many different tasks that need to be completed, before the project can be considered done. The Keystone user would set up a slip with a title of 'Set up new server', and then make many child slips with the individual tasks, possibly all assigned to different technicians. In this way, someone could go to the parent slip and see all the child slips associated with it, and their status.

Perl

Probably the most popular public domain scripting language. Perl is primarily used on Unix systems to do a variety of tasks, from web scripts to system maintenance. Some of the support utilities for Keystone are written in Perl, and the upcoming command line / email interface will be completely written in Perl. More information is available on the newsgroup news://comp.lang.perl or on the website http://www.perl.org.

PHP

A free server-side scripting language written by the PHP Development Team. More detail on credits for PHP is available here. More information on PHP in general is at http://www.php.net. Keystone is written entirely in this language.

PTS

The predecessor to Keystone, written by Dave Belfer-Shevett starting around January, 1996. All development on PTS has stopped in favor of Keystone.

PostgreSQL

A public domainm database server available at http://www.postgresql.org. PostgreSQL is a favorite for many C programmers, but is more complex to install and maintain than MySQL. Keystone does, however, support it.

Resource

A physical item, such as a computer, monitor, etc, that has been entered into Keystone for tracking purposes. Resources have unique inventory identifiers, much like slips do. They can be 'associated' with other resources to help track movement of the item. An example would be inventories components making up a particular computer system, and associating them together. When the system is moved, all the components move as well.

SID

Slip ID. A unique number identifying a particular slip.

Slip

The basic component of data within the Keystone system. A slip can be considered an 'action item', or 'something that needs to be done'. Slips have Slip identification numbers (SID's), which are unique throughout the system. A slip contains all the information regarding itself, such as who opened it, when it was opened, who it's currently assigned to, etc. A slip can have any number of 'child slips' associated with it, as well as being a child itself (ala, having a 'parent'). Child slips and Parent slips are defined elsewhere in the Glossary.

SQL

Structured Query Language. Initially developed at IBM, SQL has become the standard way to access data within a relational database. There are many resources on the Internet for more information on how to use SQL.

Reports are stored as '.rep' files, and contain definitions on how the report should look, including prompting the user for information, formatting output, and running PHP code before, during, and after the report.

A very simple .rep file may look like this (this is 'slipsbytech.rep', distributed with Keystone) :

	TITLE: Open slips by Technician
	VERSION: 1.1
	REQUIRES: 0.40.01
	DATASET: slips
	SQL:
	{
		select count(slips.sid), slips.currtech, status.label, status.flag
			from slips, status
			where slips.status = status.flag
			group by slips.currtech, status.label, status.flag
	}
	
	COL1:
	{
		label = Current Tech
		display = currtech
	}

	COL2:
	{
		label = Status Code
		display = label
	}
	COL3:
	{
		label = Number of slips
		display = count(slips.sid)
	}	

Reports contain various 'fields' that contain information required to run the report. These are:
• TITLE
  The title of the report. Will show up in the title bar of the browse window, as well as at the top of the report
• VERSION
  The version number of the report. .rep files may be distributed apart from Keystone in the future. This allows the user to check which version of the report is being run.
• REQUIRES
  As Keystone develops, the reporting system will gain new functionality, and the system will gain new structures. This entry defines what version of Keystone is required to run this report
• DATASET
  Which resource will this be run against? (Library, Slips, Resources, or Contacts
  
• SQL
  What SQL commands should be executed to generate the data output for the report? The SQL commands may contain $VAR1..$VAR9 references which will be substituted at runtime.
• VAR1..VAR9
  Prompted variables. VAR blocks contain descriptions of user-inputted data. An example:

  	VAR1:
  	{
  		text = Enter a start date
  		dtype = date
  		default = 05/12/98
  	}
  	

  (valid types are 'date', 'time', 'datetime', or 'text') Values entered here by the user are available as '$VAR1..$VAR9' within the SQL and PHP code within the report.
• COL1..COL9
  Column headers for each column of output from the SQL command. 'label' contains the column header, 'display' contains the SQL variable which will show up on each row.

  	COL1:
  	{
  		label = Current Tech
  		display = currtech
  	}
  	

PHP command blocks
Keystone supports PHP command blocks within report files. These blocks contain PHP code that is executed before, during, and after the report has run.

• PHPSTART
  This block contains code that will be executed before any output is generated. It may contain setup variables, etc.
• PHPHEAD
  This block contains code to be executed at the beginning of each page. It may contain HTML formatting code, column headers, etc.
• PHPITERATE
  The iterative command to use rather than a SQL block. This should be in a form that would go inside a 'while' statement, ie '$foo == 1';
• PHPBODY
  This block contains code that will be executed on each iteration of the report loop
• PHPFOOT
  Bottom of each page
• PHPEND
  End of the report, contains summary information, etc.

Database Schema
Keystone uses several tables stored in a SQL server. The structures are loaded from definition files stored in the ./struct/ directory distributed with the system. The tables and their uses are:

Table name	Title	Description of Contents
acclist	Accessories List	Defines how Accessories are related to parents in the Resources system. Column Def Relation Description al_parent char(10) -->resources.r_tag The resource this entry is desribing. al_acctag char(20) -->resources.r_tag The tag of the accessory associated with the 'al_parent' resource.
addresses	Addresses	Every contact within Keystone can have multiple Addresses assocaited with it. This table lists the addresses associated with a specific contact. Column Def Relation Description tag char(10) -->contacts.tag The contact this entry is associated with label char(10) A text string describing this address. 'HOME' 'WORK' etc main char(1) A flag specifying if this Address entry is considered the 'main' one, ala will be used by default when viewing slips for this contact. (1 = yes) address1 char(40) First line of address address2 char(40) Second line of address city char(20) City state char(30) State pcode char(15) Postal code
attachments	Attachments	This table is in it's infancy, but it will describe how attachments to slips are stored on the filesystem, showing who uploaded what attachment when. Column Def Relation Description _rowid int(10) Internal counter (autoincrement) at_sid int(10) -->slips.sid The slip that this attachment is associated with. at_fname varchar(45) the Filename at_tech varchar(10) -->people.login The technician who uploaded the attachment. at_date int(11) The date of the upload at_comment varchar(100) Any comments
classes	Resource classes	A list of classes a resource can be classified into. Column Def Description cl_tag char(2) A text 'shortcut' for the class (eg MD) cl_label char(15) Description of the class (eg Modem)
contacts	Contacts	This is the master table for Contacts. It is keyed on 'tag', a unique identifier for each Contact within the system. Column Def Description tag varchar(10) The contact tag (unique, key) name varchar(40) The full name of the contact company varchar(50) Company name phone varchar(20) Phone number (unused?) email varchar(50) Email address (unused?) passwd varchar(15) A password that the contact can use to view their slips on the public interface. (not yet implemented) ctype char(1) Contact Type. C = Customer, M = Manufacturer comment blob A freehand comment
dictionary	Table Dictionary	Occasionally the system needs more information about columns within tables in the system, such as when doing edits on raw tables in Maintenance, etc. This table contains descriptions and additional information for some of the tables and columns within Keystone. It is primarily used by 'properties' (to get english readable column names), and during edits in 'mbrowse'. It is keyed on 'dtable' (the name of the table) and 'dcolumn' (the column within that able). Column Def Description _rowid int(10) Internal counter (autoincrement, key) dtable varchar(15) Table name dcolumn varchar(15) Column name dflags varchar(80) 'Primary key' dlabel varchar(20) The label to show to the user for this column dheading varchar(10) The short heading for this dtype char(1) Type handler. C = Char, D=Date,
ebulk	Bulk Data Storage	Keystone allows extensions of the basic data using 'eschema' Extended Schema) definitions. This table stores the data defined in the extended schema. Column Def Description _rowid int(10) Internal counter (autoincrement) btable varchar(15) The table this piece of data is associated with belement varchar(15) The new 'column' name from eschema bvalue varchar(80) The actual datum browref int(10) a 'reference' pointer back to the associated table bkeyref varchar(80) the text version of 'browref'
eschema	Bulk Data Schema	This table contains the extended schema definitions for the data stored in the ebulk table (qv). Column Def Description _rowid int(10) Internal counter (autoincrement) etable varchar(15) The table to associate with element varchar(15) The name of the new element etype char(1) Type data type (I = Integer, C = Char, etc) eflags varchar(80) Any processing flags esequence int(2) A 'sequence' number - used to choose what order to show new fields. elength int(2) The field size of the new element elabel varchar(20) The text label to show the user for this element.
filters	System Filters	Users and admins can create customized 'filters' that are applied against the current dataset (slips / resources / contacts). All filters are stored in this table. Column Def Relation Description _rowid int(10) Internal counter (autoincrement) uid varchar(20) -->people.login The user who owns this filter fdesc varchar(40) A short description ftable varchar(10) The table this filter is to apply to (slips, resources, etc) fpublic int(1) Can other users other than the owner use this slip? (1=yes) fselect varchar(200) The actual filter statement. It is in the form of a SQL command, past the field list. Ala from the 'where...' forward
followups	Slip History	Any activity on a slip creates a 'followups' entry that describes what happened. Followups can be generated by user input (someone adding a comment) or automatically (some action caused a slip to change). The followups table is keyed on f_sid, which is a relation to the 'slips' table, on the slip ID. Column Def Relation Description _rowid int(10) Internal counter (autoincrement) f_sid int(11) -->slips.sid The Slip this followup is associated with f_date int(11) The date the followup was added f_tech varchar(10) -->people.login The technician responsible f_text blob The text of the followup f_seq int(11) A sequence number (unused) f_public int(1) Is this followup public? (1=yes) f_usergen int(1) Was this followup user generated (ala, not an automatic followupgenerated by the system) (1=yes) f_time int(4) How much time was spent for this activity?
groups	Groups definitions	Keystone has a concept of 'groups' where tickets can be categorized to different workgroups or topics. This file defines the groups within the system. Note that much of the 'groups' functionality has been replaced by the 'members' table. Column Def Description g_id varchar(10) The group ID g_assign char(1) Is this group 'assignable', IE should it show up in the pulldown when users are adding slips as a potential 'assignment'? g_people varchar(50) Unused
library	File Library	Keystone allows many attachments to be uplaoded into the system. The 'library' keeps track of those attachments that should be in the public download section, such as patches, updated software, and the like. The library is not fully functional (yet. :) Column Def Description li_fname varchar(45) Filename li_fsize int(10) File size li_update int(11) Date of last update li_uptech varchar(10) Technician last updating it li_title varchar(80) A short title li_descrip blob A description li_public int(1) Is this item 'public', and accessible by anyone? (1=yes) li_oname varchar(25) *** unknown? ***
members	General purpose groups	This table holds grouped data, using an 'id' and an 'element'. It's used for things like 'members of the admin group', where a single group 'admin' has multiple entries 'bob','frank','harry','dave'. Column Def Description id char(10) element char(20)
modules	Bugtracking Modules	When tracking bugs in Keystone, this table contains the modules that bugs can be assigned to. Column Def Description mod_name varchar(40) mod_desc varchar(80)
people	User table	This table contains all the users that can log in to Keystone and manipulate tables. It is the equivelent of a unix '/etc/passwd' file. Column Def Description login char(10) The login name (key) fullname char(40) Full username passwd char(50) The users password email char(60) the users' email address grp char(10) The default group (deprecated) company char(20) Company name (if appropriate) lastlog int(11) Last time the user logged in
phones	Contact Phone numbers	A contact in Keystone can have multiple phone numbers associated with it. This table contains those entries. Column Def Relation Description tag char(10) -->contacts.tag The contact this phone number is associated with label char(10) The label for this entry (ie HOME, CAR, CELL) main char(1) Is this the 'main' entry? (see Addresses for details) number char(50) The phone number
platforms	Bugtracking Platforms	When using bugtracking, this table defines the platforms that show up in the pulldown menu for the bug. Column Def Description plat_name varchar(40) plat_desc varchar(80)
policy policy_grp policy_login	Policy tables	These tables are used to control the ACL system, documented elsewhere in this page. Column Def Description pid int(11) fullname char(40)
preferences	User preferences	This table is updated via the 'properties' function within Keystone. It contains things such as current display settings, etc. Column Def Relation Description _rowid int(10) Internal counter (autoincrement) pr_uid varchar(15) -->people.login The username pr_tag varchar(30) An internal text tag identifying the property pr_operator varchar(5) The operation for the tag (ie '=') pr_value varchar(100) The value to be compared (ie 'fred') pr_table varchar(15) The table associated with this property
products	Bugtracking products	A listing of products that is available when doing bugtracking. This table populates that pulldown. Column Def Description prod_name varchar(40) prod_desc varchar(80)
propdisp	Display properties	This table contains the information set up in the Slips->Properties pick for what columns are displayed where. It's structure is complex, but is similar to 'preferences' above. Note also that this table can contain a wide variety of data. Column Def Relation Description _rowid int(10) Internal counter (autoincrement) p_uid varchar(15) -->people.login The username these properties work with p_flags varchar(10) p_dataset varchar(10) Which dataset this property applies to p_column varchar(15) Column name p_order int(2) A 'sequence' - where in the column order should this column appear on the screen? p_active int(1) Display this column or not? (1=yes) p_subtable varchar(15) Is this column in a JOIN'ed table?
rescodes	Bugtracking resolution codes	Codes that can be used when setting how a bug was resolved Column Def Description res_code char(1) res_desc varchar(40)
resources	Resources	The Resources master table, keyed on 'r_tag' (a unique character identifier). Note that Resources contains Resources and Accessories. They are seperated via 'r_multi' (meaning there can be more than one Accessory in a sytem for a given resource tag.) Column Def Relation Description r_tag varchar(10) The resource tag (unique) eg "DA-213" r_ptag varchar(10) The parent for this resource r_multi int(1) Can there be many of these? Ala, is this an accessory? r_serno varchar(25) Serial number r_mctag varchar(20) -->contacts.tag Manufacturers Contact Tag r_mcphone varchar(10) -->phones.tag Manufacturers phone number for the abovecontact? r_mcadd varchar(10) -->addresses.tag Manufacturers Address for this contact r_model varchar(20) Model r_class char(2) -->classes.cl_tag Class r_loc varchar(10) Location of this item r_qoh int(5) Quantity on hand r_desc varchar(80) Description r_status char(1) Status r_currtech varchar(10) -->people.login Current technician (can be used for anything, really r_ctag varchar(20) -->contacts.tag Contact tag r_cphone varchar(10) -->phones. Contact phone r_cadd varchar(10) Contact addresse r_u1val varchar(50) User defined field 1 r_u2val varchar(50) User defined field 2 r_u3val varchar(50) User defined field 2 r_u4val varchar(50) User defined field 2 r_u5val varchar(50) User defined field 2
severity	Bugtracking severity	This populates the pulldown describing the severity of a bug entered into the bugtracking section of Keystone Column Def Description flag char(1) label char(15)
slips	Slips	The Slips master table. Virtually everything in the system keys back to this table, using the slip ID (sid) as the key. Column Def Description sid int(11) slip ID (unique) spid int(11) -->slips.sid this slips parent ID depend int(11) Dependent on (not used) o_date int(11) Open date (unix timestamp) o_tech varchar(50) -->people.login Open tech c_date int(11) Close date (unix timestamp c_tech varchar(10) -->people.login Close tech currtech varchar(10) -->people.login Current tech state char(1) Unused status char(1) -->status.flag Current status priority int(11) Priority ctag varchar(20) -->contacts.tag Contact name problem varchar(80) One line description of the problem summary blob Full text problem description so_date int(11) Scheduled open date (unix timestamp) - used only if 'scheduling' is enabled sc_date int(11) Scheduled close date (unix timestamp) - used only if 'scheduling' is enabled grp varchar(10) -->groups.g_id Group belonged to is_public char(1) Is this slip public? (1=yes) l_activity int(11) Last activity (unix timestamp) l_tech varchar(50) -->people.login Last activity tech num_children int(2) Number of children (calculated column) num_follows int(2) Number of followups (calculated column) timespent int(5) Total time spent (calculated) spolicy int(2) -->policy.pid Access policy caddlabel varchar(10) -->addresses.tag Contact address cphonelabel varchar(10) -->phones.tag Contact phone number severity char(1) -->severity.flag Ticket severity
slipver	Bugtracking versions	This table contains the bugtracking information for a specific slip. Note it's only accessed if bugtracking is enabled. Column Def Description v_id int(11) -->slips.sid Associated slip v_prod varchar(40) -->products.prod_name Which product? v_mod varchar(40) -->modules.mod_name Which module? v_plat varchar(40) -->platforms.plat_name Which platform v_foundin varchar(20) -->versions.ver_name What version was this found in? v_target varchar(20) -->versions.ver_name What version will this probably be fixed in. v_verify varchar(20) -->versions.ver_name What version was this verified fixed in? v_resolve char(1) -->rescodes.rescode What was the final resolutioin?
state	State maintenance	This table contains the information on the 'state' of the users last view. This is how Keystone 'remembers' what slip you were looking at, or how your screen was configured from the last time you logged in. Column Def Description _rowid int(10) a unique row identifier (auto_increment) uid varchar(20) -->people.login The userid (unique) mslip int(1) Is the 'slip' menu expanded? (1=yes) mcont int(1) Is the 'contacts' menu expanded? (1=yes) mresource int(1) Is the 'resources' menu expanded? (1=yes) mdataset varchar(10) Which dataset are we working with? (slips, resources, library, maint, or contacts) mother int(11) Is the 'other' menu expanded? (1=yes) slipzoom int(8) -->slips.sid The slip we're zoomed in on (0 = none) resazoom varchar(10) -->resources.r_tag The Resource Accessory we're zoomed in on (0=none) filters int(1) -->filters._rowid Which filter? (0=none) filtlist varchar(200) Unused properties varchar(200) Unused contzoom varchar(10) -->contacts.tag Which contact are we zoomed to? (0=none) mlibrary int(1) Is the 'library' menu expanded? (1=yes) libzoom varchar(30) -->library.li_fname Which library entry are we looking at? (blank=none) cbgn int(4) Contacts Begin - which number contact should we start displaying? (0=beginning) (used in 'prev/next' screens) sbgn int(4) Slips Begin - which number contact should we start displaying? (0=beginning) (used in 'prev/next' screens) resrzoom varchar(10) -->resources.r_tag Which resource are we zoomed on? (blank=none) resset varchar(10) Which resource set? (res or acc) rabgn int(4) Resources Accessory Begin - which number contact should we start displaying? (0=beginning) (used in 'prev/next' screens) rrbgn int(4) Resources Begin - which number contact should we start displaying? (0=beginning) (used in 'prev/next' screens)
statelist	List information	This table has listed information for the state for the user. Examples woudl be a list of slips that are expanded. Column Def Relation Description sl_login varchar(10) -->people.login The username sl_table varchar(10) The value in 'sl_column' refers to what table? sl_flags varchar(10) What is this entry for? ('this' refers to the entry in 'sl_column') F = This slips followups are expanded M = This slip is expanded in the Main view C = This slips children are expanded O = This slips contacts are expanded V = This slips bugtrack versions are expanded P = This contacts phone numbers are expanded S = This contacts slip view is expanded A = This contacts addresses are expanded FILT = This tables filter is this sl_column varchar(10) The value being referenced (hard to explain)
status	Slip Status tags	The data that goes into the 'status' pulldown. Column Def Description flag char(1) label char(15)
versions	Bugtracking versions	This contains information for the 'versions' pulldown for bugtracking versions. Column Def Description ver_name varchar(40) ver_desc varchar(80)