SDM Design Documentation

I. Essentials

User directory: /sdm
Sitewide administrator directory: none
Data model: /packages/sdm/sdm.sql
Requirements document: /arsdigita/doc/requirements/sdm.html
Design document: this file...
Page Flow: /arsdigita/doc/page-flow/sdm_interaction_admin and /arsdigita/doc/page-flow/sdm_interaction_users
ER Diagram: /arsdigita/doc/er-diagrams/small_sdm_er

II. Introduction

The Software Development Manager (SDM) is a web-based application that, as the name suggests, helps manage the development of software projects. Based on a software-centric data model, the SDM provides functionality such as bug reporting, bug tracking, and release management. For the project coordinator, SDM is a way of staying on top of a project's status. For the developer, SDM let's them know what bugs need to be fixed and which features must be implemented. For the end-user, SDM is a feedback mechanism for reporting bugs and a source of information for downloading releases.

III. Historical Considerations

SDM is a unique ACS 3.x module in that it was primarily developed outside of ArsDigita. SDM was conceived by Philip Greenspun and Ben Adida and then implemented by Ben as part of OpenACS. In July of 2000 SDM was ported from the Postgres OpenACS version to Oracle by Dennis Gregorovic and Todd Nightingale. During this port the code was brought up to ACS 3.4 conventions and parts of the data model and user interface changed. However, the version of SDM used by ArsDigita today remains faithful to its OpenACS origins.

IV. Data Model Discussion

The data model for SDM is centered around four tables: sdm_packages, sdm_modules, sdm_package_releases, and sdm_tickets. Each of these tables represents a key "object" in the SDM system. These tables also reference each other and these references establish relationships between the objects. For example, tickets always belong to exactly one package, but may belong to zero or one module within that package.

Of course, these four tables do not make up the entire data model. There are more tables, views, and PL/SQL functions that are necessary for full functionality. Here are some of the more notable:

Tables
- sdm_package_admins provides a mapping of package administrators.
- sdm_module_users provides a mapping of module users.
- sdm_ticket_status provides a list of valid status ticket values.
- sdm_ticket_severity provides a list of valid ticket severity values.
- sdm_ticket_ratings keeps track of user ratings for each ticket.
- sdm_ticket_assignments provides a mapping of who is assigned to each ticket.
- sdm_user_ticket_interest_map provides a mapping of who is interested in each ticket.
- sdm_user_package_interest_map provides a mapping of who is interested in each package.
- sdm_notifications keeps a listing of package and ticket change notifications.
- sdm_notification_prefs keeps track of each user's notification preferences.
PL/SQL Functions
- sdm_user_can_edit_release_p is used to determine if a user can edit a release. There are similar functions for editing and viewing packages and modules.
- sdm_release_lessthan_p is used for comparing release versions.
- sdm_ticket_assigned produces a list of users assigned to a particular ticket.
- sdm_package_add_notification adds a notification to sdm_notifications for a particular package.
- sdm_ticket_add_notification adds a notification to sdm_notifications for a particular ticket.
- sdm_tickets_notification_tr is a trigger on sdm_tickets that automaticaly adds notifications when tickets are modified.

V. Legal Transactions

/www

Users may

Add tickets

SDM Administrators may

Add packages

/www/pvt

Users may

Edit ticket status, severity, expected completion, type, and description
Add and Edit notification preferences
Add ticket assignments

Package Administrators may

Edit packages
Edit all ticket information
Add and Delete package admins
Add and Delete module users
Add, Edit, and Delete modules
Add and Edit package releases
Add and Delete ticket assignments

VI. API

The following Tcl procedures are defined in the application definition file.

sdm_url_stub {}: The URL for content under the application. Defaults to "/sdm"
sdm_software_root {}: The directory where uploaded software is stored
sdm_version {}: The version of the module
sdm_notification_sender_email {}: The email address to be placed in the 'From' field for notification email.
sdm_home_context_bar_item {}: Context bar item for the home page of SDM
sdm_module_context_bar_item {module_id module_name}: Context bar item for specified module
sdm_package_context_bar_item {package_id package_name}: Context bar item for specified package
sdm_package_release_context_bar_item {release_id release_name}: Context bar item for specified release
sdm_header {title}: Default header HTML for application pages
sdm_footer {}: Default footer HTML for application pages
sdm_system_name {}: Name of the SDM system
sdm_default_severity {}: Returns the default ticket severity
sdm_list_of_ticket_types {}: Returns a list of ticket types
sdm_list_of_severities {}: Returns a list of severity options
sdm_list_of_notification_prefs {}: Returns a list of notification interval preference options
sdm_ticket_status_id {ticket_status}: Returns the ID of the specified ticket status
sdm_severity_id {ticket_severity}: Returns the ID of the specified ticket severity
sdm_return_access_complaint {}: Returns an access violation error page to the user
sdm_check_admin {}: Checks where the current user is an SDM administrator
sdm_verify_admin { conn args why }: A filter that only passes for SDM admins
sdm_user_can_add_packages { user_id }: Checks whether the user has permission to add packages
user_can_see_package_p { user_id package_id }: Checks whether the user has permission to see the specified package
user_can_see_module_p { user_id module_id }: Checks whether the user has permission to see the specified module
user_can_edit_package_p { user_id package_id }: Checks whether the user has permission to edit the specified package
user_can_edit_release_p { user_id release_id}: Checks whether the user has permission to edit the specified release
user_can_edit_module_p { user_id module_id}: Checks whether the user has permission to edit the specified module
make_user_select_html { sql_query {name user_id}}: An HTML widget that create a selectable list of users from the query
sdm_valid_status_transitions {}: Returns a list of valid ticket status transitions
sdm_valid_transitions { start_state}: Returns a list of valid ticket status transitions for the given start state in the current stack frame<
sdm_transition_is_valid_p { transition }: Checks whether the specified transition is valid
set_simple_user_information {}: Sets the folllowing user information variables: user_id, user_logged_on_p, first_names, last_name, email
set_simple_module_information { module_id }: Sets the following module information variables: module_name, package_id, package_name, package_private_p, module_private_p
set_simple_package_information { package_id }: Sets the following package information variables: package_name, package_private_p
sdm_software_dir { package_id release_id {module_id ""} }: Returns the directory path for the specified release
sdm_release_filename { release_id original_filename }: Returns the filename for the release
sdm_cleanup_filename {filename}: Removes extra characters from filename
sdm_code_license {}: Returns the license for uploaded code
sdm_download_package_release { ignore }: Serves a package release file
sdm_user_has_rated_ticket_p { user_id ticket_id }: Returns 1 if the user has rated the ticket, 0 otherwise
sdm_rate_ticket { user_id ticket_id rating }: Enters the user's rating for the ticket into the database
sdm_ticket_rating { ticket_id }: Returns the average rating for the ticket
sdm_ticket_n_interested_users {ticket_id }: Returns the number of users interested in the ticket
sdm_ticket_user_is_interested_p {ticket_id user_id }: Returns 1 if the user is interested in the ticket, 0 otherwise
sdm_ticket_user_is_interested {ticket_id user_id }: Registers the user as being interested in the ticket
sdm_ticket_user_is_not_interested { ticket_id user_id }: Registers the user as not being interested in the ticket
sdm_package_n_interested_users { package_id }: Returns the number of users interested in the package
sdm_package_user_is_interested_p { package_id user_id }: Returns 1 if the user is interested in the package, 0 otherwise
sdm_package_user_is_interested { package_id user_id }: Registers the user as being interested in the package
sdm_package_user_is_not_interested { package_id user_id }: Registers the user as not being interested in the package
sdm_ticket_notify { what ticket_id subject body {excluded_users {}}}: Immediately notifies relevant users of an action performed on a ticket
sdm_notify_users_ticket { ticket_id notification }: Adds the notification for the specified ticket into the notifications table
sdm_notify_users_package {package_id notification }: Adds the notification for the specified package into the notifications table
sdm_send_one_email {to from subject body}: Send an email with an SDM footer after the body
sdm_send_notifications { interval }: Sends email out for notifications
sdm_remove_notifications { interval }: Clears out old notifications from the database

VII. User Interface

User features

There is a 'My SDM' page which lists packages and releases managed by the user in addition to all tickets opened by or assigned to the user.
There are links on every page to 'My SDM' and 'Help'.
The user can see a list of all oustanding or resolved bugs and feature requests in a package.
The user can sort this list by ticket ID #, rating, #interested, severity, module, assigned to, expexcted completion, or summary.
The page which displays the details of a single ticket is divided into two sections - 'community' and 'feature information'.
These community aspects are reflected in other places, such as the # interested column in the ticket listings.

VIII. Configuration/Parameters


[ns/server/service_name/acs/sdm]
; Do we allow users to comment on tickets?
SolicitCommentsP=1
CommentApprovalPolicy=open
UrlStub=/sdm
; This is where uploaded tarballs are stored
SoftwareRoot=/web/my_service/sdm-software
SdmVersion=1.0
NotificationSenderEmail=webmaster@yourdomain.com
SystemName=Software Development Manager
DefaultSeverity=medium

IX. Acceptance Tests

Here is a list of actions that you should test ( * indicates that you must be an admin to perform this action):

Create a package. *
Change the package description and package name. *
Create a module in the package. *
Change the module description, module, name, and module owner. *
Create a release for the package. *
Change the version of the release. *
Create a ticket in the package but not associated with a module.
Create a ticket in the package and associate it with a module.
Change the severity of the ticket.
Change the description of the ticket.
Change the type of the ticket.
Set the expected completion for both tickets.
Assign a ticket to yourself.
Assign a ticket to someone else.
Mark a ticket as fixed. Verify that the ticket submitter and users assigned were notified.
Make the release live. Verify that the open ticket is listed. *
Create another release. *
Take back the first release and make the second one live. *

X. Authors

System creators: Philip Greenspun, Ben Adida
System owner: Dennis Gregorovic
Documentation author: Dennis Gregorovic

dennis@arsdigita.com

Last modified: $Date: 2001/01/22 04:24:08 $