Ticketing System
Relevant source files
The following files were used as context for generating this wiki page:
The Ticketing System is a central helpdesk module within the IT Management System designed to manage support requests. It serves as the primary interface for IT support operations, allowing users to track issues from inception to resolution while maintaining historical records through a strict archiving policy rather than deletion.
The system is fully integrated with other modules, specifically linking tickets to assets (Equipment) and users (Employees/Assigned Technicians). It supports multi-tenancy by enforcing strict company_id scoping for all data access and operations.
Sources: modules/tickets/AGENT_NOTES.md:1-25, wiki/Modules.md:105-107
Architecture and Data Model
The Ticketing System relies on a central tickets table which acts as the hub for various relational lookups. These lookups provide classification, prioritization, and ownership context for each support request.
Entity Relationships
The following diagram illustrates the core relationships of the tickets entity:
The system uses foreign keys to link tickets to specific companies, categories, and statuses. It also maintains a link to equipment to facilitate asset lifecycle tracking through support history.
Sources: modules/tickets/AGENT_NOTES.md:5-15, modules/tickets/create.php:175-185, modules/tickets/view.php:50-65
Functional Components
1. Ticket Lifecycle Management
Tickets progress through various statuses (e.g., Open, Closed). A critical business rule prevents the deletion of tickets to preserve history; instead, the system utilizes an archiving mechanism.
- Archiving: Tickets can be archived or un-archived via a dedicated API endpoint (
modules/tickets/archive.php). - Asset Linking: Every ticket can be associated with an "Affected Asset" from the equipment inventory, enabling technicians to view the support history of specific hardware.
Sources: modules/tickets/AGENT_NOTES.md:17-22, scripts/api.php:115
2. Media and Photo Management
The system supports multiple photo/screenshot uploads per ticket to assist in troubleshooting.
- Storage: Photo filenames are stored as a JSON array in the
tickets_photoscolumn. - Processing: The system performs MIME type detection and unique filename generation (pattern:
ticket_{id}_{timestamp}_{rand}.{ext}) during upload. - Upload Path: Physical files are stored in a dedicated
tickets_photos/directory.
Sources: modules/tickets/create.php:15-55, README.md:200-205
3. UI and Visualization
The interface utilizes color-coded badges to provide quick visual status and priority indicators. These colors are derived from the ticket_statuses and ticket_priorities tables.
| Component | Description |
|---|---|
| Search & Filter | Extensive filtering by status, priority, and assigned user. |
| Color Badges | Renders labels with dynamic background transparency based on hex color values from lookup tables. |
| Gallery View | A thumbnail-based view of all attached screenshots within the ticket detail page. |
Sources: modules/tickets/AGENT_NOTES.md:27-30, modules/tickets/view.php:30-45
API Endpoints and Integration
The Ticketing System exposes several internal AJAX/JSON endpoints used by the frontend and external tools.
Key API Actions
| Endpoint | Method | Purpose | Required Parameters |
|---|---|---|---|
modules/tickets/index.php | POST | Bulk Excel/CSV import using import_excel_rows. | csrf_token, import_excel_rows (JSON) |
modules/tickets/archive.php | POST | Toggle archive status of a ticket. | id, archive_action, csrf_token |
api-examples/tickets.php | POST | Standalone example for bulk ticket creation. | Varies by implementation |
Sources: scripts/api.php:50-65, scripts/api.php:115-120, modules/tickets/AGENT_NOTES.md:32-35
Import Logic Flow
The system supports bulk importing rows via JSON, which is typical for the "Import Excel" flow found across modules.
Sources: scripts/api.php:40-60, scripts/api.php:235-245
Security and Multi-Tenancy
As with the core project, the Ticketing System adheres to strict security standards:
- Multi-Tenant Isolation: Every SQL query includes a
company_id = ?filter, ensuring users only see tickets belonging to their own organization. - CSRF Protection: All state-changing operations (Create, Edit, Delete, Archive) require a valid
csrf_token. - Prepared Statements: The system uses
mysqliprepared statements to prevent SQL injection during ticket creation and retrieval.
// Example of tenant-scoped prepared statement for ticket retrieval
$stmt = mysqli_prepare($conn, 'SELECT * FROM tickets WHERE id = ? AND company_id = ? LIMIT 1');
mysqli_stmt_bind_param($stmt, 'ii', $id, $company_id);
mysqli_stmt_execute($stmt);
Sources: modules/tickets/AGENT_NOTES.md:38-45, modules/tickets/create.php:245-255
Conclusion
The Ticketing System provides a robust framework for managing IT support within a multi-company environment. By integrating directly with the equipment and user modules and enforcing a non-destructive archiving policy, it ensures that organizations maintain a comprehensive and accurate audit trail of all support activities and asset performance.