1.2. Ticket Tracker Design Document

1.2.1. Essentials

• User directory

• Administrator directory

• Tcl API

• PL/SQL API

  • ttracker_ticket

  • ttracker_category

  • ttracker_util

  • ttracker_callback

• Data model:

  • ticket-tracker-create.sql

  • ticket-tracker-drop.sql

  • ticket-tracker-packages.sql

  • ticket-create.sql

  • category-create.sql

  • options-create.sql

  • ttracker-workflow-create.sql

  • ttracker-workflow-drop.sql

• Ticket Tracker Requirements

1.2.2. Introduction

Ticket Tracker is an ACS 4.0 package that provides end users with a centralized collaborative means for managing tickets. Ticket Tracker uses the workflow engine to track and manage tickets (i.e., state of the ticket, who is assigned to the ticket).

1.2.3. Historical Considerations

In past 3.x ACS releases, the Ticket Tracker was mainly used to track bugs and feature requests for projects. The SDM package has since emerged from the Ticket Tracker to handle just this. The Ticket Tracker is a more of a general-purpose issue management service intended to handle any type of project. The SDM can be seen as a specific ticket-tracker.

Ticket Tracker for ACS 4.0 does not implement all features provided by the 3.x version. This version has been redesigned from scratch in order to take advantage of the object model in ACS 4.0.

The most noticeable feature change is that users no longer define "Projects". Instead users would mount another instance of the ticket tracker package. This solutions allows administration for different ticket trackers through the site-map admin pages.

1.2.4. Competitive Analysis

incomplete

1.2.5. Design Tradeoffs

The main problem with the 3.x ticket tracker was that it was too slow. During the data model redesign, we kept this in mind and came up with some ideas to help speed up access to ticket information:

• Stored duplicate data. The creation_user and creation_date are almost always needed when retrieving data for a ticket. Instead of adding the extra overhead of joining against the acs_objects table, this information was also stored in the ttracker_tickets table.

• Minimize number of tables. Since we also had to join with the acs-workflow tables to retrieve ticket state and other information, we had to cut down on the number of tables to hold Ticket Tracker relevant data. Ticket-tracker has two tables: ttracker_tickets and ttracker_categories

• Used other ACS packages to store information Subsites allowed us to get rid of projects, thus each Ticket Tracker package instance serves as a project container in which tickets are grouped. Tickets are further separated by the ttracker_category table. Subsite parameters are also used to hold extra instance level data. For now they hold customization strings for category aliasing. The usage of the workflow case assignments table saves us from making an extra mapping table for ticket assignments.

The main work of the Ticket Tracker really lies within the workflow engine. The workflow engine keeps track of the current state of the ticket, who is assigned to the ticket, and other important information. We had to keep in mind that the ticket-tracker was going to serve a very general audience in terms of project management, thus the workflow used had to be simple. There are plans of a customizable workflow on a per-package-instance level for future releases of the Ticket Tracker.

However, using workflow also introduces additional complexity. In most SQL queries, multiple workflow tables need to be joined and performance is hindered as a result.

1.2.6. API

No API is provided right now. Although there's an idea that the ticket tracker pacakge might be able to talk to the portal package later on...

1.2.7. Data Model Discussion

The datamodel is quite simple, since the majority of the work is done in ACS-workflow. There are three tables:

• ttracker_categories

  • Contains infomation about categories and default assignees.

  • 0 or 1 default assignee per category.

• ttracker_tickets

  • Contains information about tickets.

  • ACS-message is the super type of ttracker_ticket so that we can send out tickets as emails in the future.

  • Duplicates the creations_user and creation_date fields in acs-objects to imporve performance.

  • Duplicates the subject field in acs-message (or more accurately, in cr_revision) to improve performance.

• ttracker_options

  • A simple mapping table that contains the name/value pair of priority and severity options.

  • Not hooked up to the ACS-object system.

The diagram above is the workflow process used in the Ticket Tracker. The process is started whenever a new ticket is entered. Within the process, several custom callbacks in the ttracker_callback package are used:

• assign_task_to_submitter

  • An assignment callback.

  • It assigns the task to the submitter of the ticket.

  • It is registered to "Clarify ticket description".

• assign_task_to_assignee

  • An assignment callback.

  • If there is a default assignee for the ticket category, it assigns the task to that party.

  • It is registered to "Resolve ticket".

• clarify_fire

  • A fire callback.

  • It sets the attribute "need_clarification" to false.

  • It is called when "Clarify ticket description" is fired.

  • Reason for existence: When "Clarify ticket description" is fired, it implies that the ticket description has been clarified already.

• resolve_fire:

  • A fire callback.

  • It sets the attribute "verified" to true.

  • It is called when "Resolve ticket" is fired.

  • Reason for existence: When "Resolve ticket" is fired, it implies that the ticket has been resolved. This is only needed if the users changes the value of "verified" to false in the previous state.

• notification:

  • A notification callback.

  • It sets the party_from, subject, and body values to send to acs-notification.

  • It obtains the party_from field from the "Notification Sender" parameter.

  • Based on the custom_arg value, it let's the receiver know of what action to take. (Since all three transitions use this callback)

• notify_admin:

  • An unassigned callback.

  • It sends emails to people who have the admin privilege on the ticket tracker instance to notify them of unassigned tasks.

  • Unlike notification, which only modifies the values of its argument, notify_admin actually calls acs_mail_nt.post_request to send the message.

Originally, another workflow process was used for the ticket tracker. (shown below) It is more complex than the current workflow process, mainly because "Assign ticket" is a task in itself. There are two reasons for it:

1. We need to email the admin whenever a ticket is unassigned.

2. If the user feels the ticket assignment is not adequate, we need to somehow notify the admin.

It turns out that [1] can be solved with the new version of acs-workflow. As for [2], we decide to allow the user to change the ticket assignment. Also an option to remove all the parties that a user is a member of is given to the user as well. Therefore, if the ticket assignee knows the right party to assign to, he or she can make the change right away. In the worst case, if nobody knows whom to give the ticket to, the users at least can remove themselves. If all ticket assignees are removed, the ticket becomes unassigned and shows up on the admin's unassigned list again.

1.2.8. User Interface

incomplete

1.2.9. Configuration/Parameters

• CategoryName:Alternative name for a category

• CategoryPluralName:Alternative plural name for a category

• NotificationSender:Party ID of the email notification sender. This party's email address will appear in the "from" field in all notifications sent out by the ticket tracker.

1.2.10. Future Improvements/Areas of Likely Change

• Advanced search.

• Customizable ticket tracker workflow on a per package instance.

• Moving/copying tickets from one ticket-tracker instance to another.

1.2.11. Authors

• Tony Tseng

• Phong Nguyen

1.2.12. Revision History

phong@arsdigita.com

Last modified: $Id: design.html,v 1.1 2002/07/09 17:35:13 rmello Exp $