Ticket Tracker Design

by Henry Minsky

I. Essentials

User directory /ticket
Sitewide administrator directory /admin/ticket
Subsite administrator directory /ticket/admin
TCL script directory /tcl
Data model /arsdigita/doc/sql/ticket.sql and /arsdigita/doc/sql/ticket-data.sql
Requirements document: /arsdigita/doc/requirements/ticket.html
Design document: /arsdigita/doc/design/ticket.html
Page Flow: /arsdigita/doc/page-flow/ticket_interaction_admin and /arsdigita/doc/page-flow/ticket_interaction_users
ER Diagram: /arsdigita/doc/er-diagrams/small_ticket_er

II. Introduction

The system is designed to meet the requirements in /arsdigita/doc/requirements/ticket.html.

III. Competitive Analysis

The ACS Software Development Module was developed independently of the Ticket Tracker, and was made specifically to assist in development of software projects, and provides some overlap with the ticket tracker functionality. The main overlap is in the area of bug tracking.

The SDM has specific features which the ticket tracker module does not such as a model of releases and modules, which allow it to model ACS software releases. However, it is currently lacking some of the advanced search and reporting facility that the Ticket Tracker module has.

The SDM is appropriate for software projects, while the Ticket Tracker module may also be better suited for non-software development projects, such as system admin, facilities, or other project tasks.

Many ticket tracking systems exist. Having one integrated with the ACS is a benefit for linking to users and groups tables, as well as for simplifying our software platform. See commercial systems such as StarTeam or free software such as Bugzilla .

The commercial systems such as StarTeam probably offer better integration with a souce control system than Ticket Tracker. Ideally, when the developer makes changes to the source tree to address a defect, that should be linked into the related record(s) in the database.

IV. Design Tradeoffs

The ticket tracker was developed over time from a much simpler data model, and in particular the issues of security where not designed in from the start. If you wish to run a single ACS ticket tracker installation to operate multiple projects where you don't want users in one project to be able to view tickets in another project, then the current security model probably has security holes to consider. The software was designed before the new ACS 4 security model, and thus it is likely that there are ways for a user to hack the URLs to view tickets from projects even if the project is not public and the user is in a different group.

V. Data Model Discussion

The ticket system has a set of core tables to hold tickets, and auxiliary project data, such as code sets. It also makes use of the general comments system to hold a trail of comments (discussions) on tickets by developers.

Code Sets

A code set is the collection of codes that a Project or set of projects use on their tickets, so for example aD can have a small set suited to small groups and HP can have a large set which reflects their formalized ticket resolution process. The codes contain the legal full and short names and values for the fields 'severity','priority','status','type','cause','source'.

A code set is typically configured for an ACS installation, and never changed after that. To update the code set with existing tickets in the database would require a conversion process.

The tables ticket_codes_i, ticket_code_sets contain the data for the code sets. The data is initialized at ACS installation by the /sql/ticket-data.sql PL/SQL file.

Internally, ticket code values are unique integers. Views such as the ticket_issues view perform the joins needed to translate the code values to user-friendly text strings.

Tickets and Projects

The ticket_projects table holds the list of all projects. The ticket_domains holds a list of subclasses by which tickets can be categorized. These are referred to as Feature Areas in the user interface.

The ticket_issues_i table holds the individual tickets. The ticket_issues_i_audit table is an audit table to hold previous versions of each ticket when the ticket is modified. The trigger ticket_issues_i_audit_tr copies a ticket's previous state to the audit table whenever it is modified.

In order to make the user-interface more productive, the table view of tickets is ordered and filtered using a customizable persistent settings vector. The persistent settings are stored in the database via the ad_custom_load API from the user_custom table.

VI. Legal Transactions

Project Transactions

For a project, the important transactions are

/ticket Ticket transactions
- Create a ticket
- Modify a ticket status field
- Modify a ticket description field (title, description body)
- Add a comment to a ticket
- Assign a ticket to a user
- Cross-link a ticket to another ticket
- Move ticket to another project
- Create an email alert (watch) on the ticket
User Interface Settings
- Create a new named table view
- Create a new named sort order filter
/ticket/admin
- Create new project
- Create new feature area
- Assign feature area to project
- Edit Feature Area
- Edit Project
- Activate/Deactivate Project
- Create a named deadline

VII. API

See the /ticket-defs section of /arsdigita/doc/procs for a list of documented Tcl library functions.

VIII. User Interface

Developers/Users
The developer should have a home page which lists the most useful summary information of what tickets they have to work on.
The /index.tcl page shows a table of one-line ticket summaries, based on the currently active (persistent) table view and sort order.
The ticket table has a dimensional set of filter controls
- By creator [me | anyone]
- By assignee [mine | everyone's | unassigned]
- By status [open | deferred | closed | all]
- By creation time [last 24hrs | last week | last month | all]
The single text search field on the page acts as an additional filter parameter, in addition to the table dimensional filters.
If the Advanced Search option is selected, then an extensive search form is placed at the top of the index page, where specific structured filter field values can be entered, such as creation date, submitter, or ticket status.
The developer can view a change log history of a ticket. The change log lists each insert or update which was done to the ticket, with the date and the user who made the changes.
A developer can add a request to be notified by email on changes to a ticket or project.
Site-wide administrators This is linked to the /ticket/admin pages
Administrators
The administration pages under /ticket/admin provide a way to list projects and to edit their properties, as well as a facility to create new projects. The projects are listed in a one-line summary table format on the index page, and links are provided to edit each project, or to copy an existing project to make a new project with the same parameters.

IX. Configuration/Parameters

At installation time, the default ticket projects and code set are loaded into the database.

The /parameters/yourserver.ini file contains a /ticket section where configuration parameters are kept.

Here is an example configuration, with comments


[ns/server/acs-dev/acs/ticket]
; When sending a note to an admin or engineer about a trouble
; ticket, what reply-to: address to use
; note that this address must be set up through your mail transfer
; agent to run a email enqueueing script.
; See doc/ticket.html for more info on configuring the ticket system.
; (from /web/acs-dev/bin/queue-message.pl)
TicketReplyEmail=support-ticket-robot@arsdigita.com

; if LinkTicketToUserGroupP = 1, each ticket is assigned to a user group
; a user must be in the group to see the ticket
LinkTicketToUserGroupP=0

; If CustomerCanCreateNewTickets = 1, customers may create new tickets.
; (A "customer" is any user who is not in the ticket admin group)
CustomerCanCreateNewTickets=1

; to tell the email queue system where to dispatch
; all of this is based on tags supplied by the mail-transfer agent
[ns/server/acs-dev/acs/email-queue]
; how often to check the queue for new messages
;QueueSweepInterval=300
; what to do with a new message
; format is tag|tcl_proc_to_invoke
;DispatchPair=ticket-tracker|ticket_process_message

X. Future Improvements/Areas of Likely Change

The ticket system ought to have a set of project-specific customizable fields, so that information which is specific to a project can be captured in a more structured way. For example, a mechanism to let an administator add a customizable picklist field for software version of release.
The security model for projects/tickets needs to be redesigned given a real set of requirements. The current system suffers from a lack of a clear model for groups and security, due largely to the historical lack of clarity in the ACS models for these system facilities.
A more flexible and configurable email notification system should be in place, which allows system admins to get email summary notifications of activity in projects, and allows users to request notification on specific transactions, in order to control the amount of email they get from the system.

XI. Authors

System creator
Jin Choi, Tracy Adams, Philg, Eve, Henry Minsky, major revisions by Jeff Davis
System owner
Jeff Davis
Documentation author
Henry Minsky