¶ Subticket Manager
¶ Table of Contents
- Requirements
- Installation
- Configuration
- Usage
- Admin Interface
- API Integration
- Troubleshooting
- Technical Details
- FAQ
¶ Overview
The Subticket Manager plugin transforms osTicket's hidden parent/child ticket infrastructure into a fully functional, user-friendly feature. While osTicket provides the database structure (ticket_pid field) and API methods (isChild(), getPid()), it lacks any user interface or workflow automation.
This plugin provides a complete solution for managing hierarchical ticket relationships with visual indicators, workflow automation, and an intuitive interface for creating and managing subtickets.
What makes this plugin essential:
osTicket already has the technical foundation for parent/child tickets built into the core system, but it provides:
- ❌ No user interface to manage relationships
- ❌ No visual indicators in ticket lists
- ❌ No workflow automation
- ❌ No easy way to create or link subtickets
This plugin makes osTicket's hidden parent/child infrastructure actually usable for daily support operations.
¶ Key Features
- ✅ Visual Parent Indicators - Code-fork icons (🔀) in queue lists show parent tickets at a glance
- ✅ Parent Badge - Prominent badge below ticket number displays "Parent Ticket (X Sub-Tickets)"
- ✅ Integrated Panel - Manage parent/child relationships directly in ticket view (appears above ticket tabs)
- ✅ Link/Unlink Tickets - Connect existing tickets or create new subtickets with one click
- ✅ Auto-Close Workflow - Parent tickets automatically close when all children are closed (Phase 4 feature)
- ✅ AJAX-Based - Real-time updates without page reloads, smooth user experience
- ✅ No Core Modifications - Uses osTicket's native infrastructure (
ticket_pid), no core file changes required - ✅ Queue Decoration - Automatic SQL query enhancement to show parent ticket indicators in all queue views
- ✅ Circular Dependency Prevention - Prevents tickets from being their own ancestors
- ✅ Auto-Linking - New tickets created via "Create Subticket" button are automatically linked to parent
¶ Use Cases
- Complex Support Requests - Break down large issues into manageable subtasks (e.g., server migration split into DNS, data transfer, testing)
- Multi-Step Workflows - Track progress across related tickets (e.g., onboarding: account creation, training, equipment setup)
- Team Collaboration - Distribute work across multiple agents with clear hierarchy (parent ticket for project manager, subtickets for team members)
- Project Management - Use parent tickets as project containers (e.g., "Website Redesign" with subtickets for design, development, testing)
- Feature Requests - Split implementation into tracked subtasks (e.g., backend API, frontend UI, documentation)
- Bug Tracking - Create separate tickets for testing, fixing, and documentation while maintaining clear relationships
¶ Requirements
| Requirement | Version | Notes |
|---|---|---|
| osTicket | 1.18.x | Plugin uses osTicket's native ticket_pid infrastructure |
| PHP | 7.4+ | Recommended: PHP 8.1+ for best performance |
| jQuery | Any | Included in osTicket by default |
| Database | MariaDB 10.3+ or MySQL 5.7+ | Plugin creates additional metadata tables |
¶ Installation
¶ Step 1: Install Plugin Files
¶ Method 1: ZIP Download (Recommended)
- Download latest release from Releases
- Extract ZIP file
- Upload
subticket-managerfolder to/include/plugins/on your osTicket server
Final path: /path/to/osticket/include/plugins/subticket-manager/
¶ Method 2: Git Repository
cd /path/to/osticket/include/plugins
git clone https://github.com/markus-michalski/osticket-subticket-manager.git
¶ Step 2: Enable Plugin in osTicket
- Login to osTicket Admin Panel
- Navigate to: Admin Panel → Manage → Plugins
- Find "Subticket Manager" in the plugin list
- Click Enable (or Install if first installation)
- Plugin will automatically:
- Create singleton instance
- Deploy admin pages (
scp/subtickets.php,scp/apps.php) - Deploy AJAX handler (
scp/ajax-subticket.php) - Create database tables and indexes
¶ Step 3: Verify Installation
-
Check Admin Interface:
- Navigate to Applications tab in staff panel
- You should see "Subticket Hierarchies" entry
-
Check Ticket View:
- Open any ticket
- Scroll down - you should see "Parent Ticket / Child Tickets" panel above ticket tabs
-
Check Queue Indicators:
- Create a parent ticket with at least one child
- Go to ticket queue (Tickets → Open)
- Parent tickets should display code-fork icon (🔀) with child count
¶ Configuration
The plugin requires no configuration - it works out of the box using osTicket's native parent/child infrastructure.
All features are automatically enabled upon plugin activation:
- ✅ Visual indicators in queue lists
- ✅ Parent badge in ticket view
- ✅ Link/unlink functionality
- ✅ Create subticket workflow
- ✅ Auto-linking for new subtickets
Optional Settings:
- Debug Mode: Set
SUBTICKET_DEBUG = trueinclass.SubticketPlugin.php(line 8) to enable detailed logging to/tmp/subticket-debug.log - Auto-Close: Configurable in future versions (currently Phase 4 feature)
¶ Usage
¶ Creating a Subticket
From Parent Ticket:
- Open the parent ticket in staff interface
- Scroll to the "Child Tickets" section
- Click "Create Subticket" button
- You'll be redirected to the "New Ticket" form (
tickets.php?a=open&subticket_parent=15) - Fill in ticket details and create the ticket
- The new ticket is automatically linked to the parent (via
model.createdsignal handler)
¶ Linking an Existing Ticket
Option 1: From Child Ticket
- Open the ticket you want to make a child
- Click "Link to Parent" in the "Parent Ticket" section
- Enter the parent ticket number or ID (e.g., "181752")
- Click "Link" to confirm
- Panel refreshes to show parent relationship
Option 2: From Parent Ticket
- Open the parent ticket
- In the "Child Tickets" section, use the admin interface to link existing tickets
- Navigate to Applications → Subticket Hierarchies for batch operations
¶ Unlinking Tickets
From Child Ticket:
- Open the child ticket
- In the "Parent Ticket" section, click "Unlink from Parent"
- Confirm the action
- Relationship is removed (
ticket_pidset to NULL)
From Parent Ticket:
- Open the parent ticket
- In the "Child Tickets" list, click "Unlink" next to any child
- Confirm the action
¶ Visual Indicators
Queue Lists:
- Parent tickets display a code-fork icon (🔀) with child count
- Hover over icon to see tooltip: "X Sub-Ticket(s)"
- Indicator is added via JavaScript (
queue-indicator.js) using AJAX endpoint - Works in all queue views (Open, Closed, My Tickets, etc.)
Ticket View:
- Parent tickets show a prominent blue badge below the ticket number:
🔀 Parent Ticket (3 Sub-Tickets) - Badge is styled with blue background and border (
background: #e8f4f8; border-left: 4px solid #1e90ff) - Badge appears in the "Parent Ticket / Child Tickets" panel
¶ Admin Interface
¶ Subticket Hierarchies Page
Navigate to: Applications → Subticket Hierarchies (scp/subtickets.php)
Features:
- Overview Dashboard - Shows all parent tickets with child counts
- Hierarchy Tree View - Visual representation of ticket relationships
- Batch Operations - Link/unlink multiple tickets at once
- Search & Filter - Find parent tickets by number, subject, or status
¶ API Integration
¶ AJAX Endpoints
The plugin provides standalone AJAX endpoints for frontend operations:
Base URL: /scp/ajax-subticket.php
¶ 1. Link Ticket to Parent
POST /scp/ajax-subticket.php?action=link
Content-Type: application/x-www-form-urlencoded
child_id=123&parent_number=181752&__CSRFToken__=abc123
Response:
{
\"success\": true,
\"message\": \"Ticket linked successfully\"
}
¶ 2. Unlink Ticket from Parent
POST /scp/ajax-subticket.php?action=unlink
Content-Type: application/x-www-form-urlencoded
child_id=123&__CSRFToken__=abc123
Response:
{
\"success\": true,
\"message\": \"Ticket unlinked successfully\"
}
¶ 3. Get Parent Ticket Status (Batch)
GET /scp/ajax-subticket.php?action=batch_parent_status&ticket_ids=15,16,17
Response:
{
\"15\": {\"isParent\": true, \"childCount\": 3},
\"16\": {\"isParent\": false, \"childCount\": 0},
\"17\": {\"isParent\": true, \"childCount\": 1}
}
¶ Queue Decoration API
The plugin extends osTicket's QueueColumnAnnotation class to add parent indicators to queue SQL queries:
Class: ParentTicketDecoration (queue-decoration.php)
Method: annotate($query, $name = false)
Functionality:
- Adds
LEFT JOINto count child tickets - Returns SQL fragment:
(SELECT COUNT(*) FROM ost_ticket WHERE ticket_pid = ticket.ticket_id) as _subticket_count - Used by
queue-indicator.jsto display icons in queue lists
¶ Troubleshooting
¶ Problem: Parent indicators not showing in queue lists
Symptoms:
- Queue lists show tickets but no code-fork icons
- Console shows no errors
Check:
- Clear browser cache (Ctrl+Shift+R)
- Check browser console for JavaScript errors:
// Open DevTools (F12) → Console tab // Look for errors from queue-indicator.js - Verify jQuery is loaded:
// In browser console: typeof jQuery // Should return \"function\" - Enable debug mode:
// In browser console: SubticketPanel.debug = true - Check AJAX endpoint:
curl \"http://osticket.local/scp/ajax-subticket.php?action=batch_parent_status&ticket_ids=15\"
¶ Problem: "No parent ticket" shown but relationship exists in database
Symptoms:
- Panel shows "No parent ticket"
- Database query shows
ticket_pidis NOT NULL
Check:
-
Verify database relationship:
SELECT ticket_id, number, ticket_pid, status_id FROM ost_ticket WHERE ticket_id = 123; -
Check if parent ticket exists:
SELECT * FROM ost_ticket WHERE ticket_id = ( SELECT ticket_pid FROM ost_ticket WHERE ticket_id = 123 ); -
Try unlinking and re-linking:
- Click "Unlink from Parent"
- Refresh page
- Click "Link to Parent" and re-enter parent number
-
Check join query in plugin code:
- Open
/tmp/subticket-debug.log(if debug mode enabled) - Look for SQL query errors
- Open
¶ Problem: Panel not visible in ticket view
Symptoms:
- Ticket opens normally but no "Parent Ticket / Child Tickets" section
Check:
-
Plugin is enabled:
- Admin Panel → Manage → Plugins
- "Subticket Manager" should show "Enabled"
-
Clear browser cache (may be hidden by old CSS)
-
Check if panel is collapsed:
- Look for
<div class=\"subticket-panel section-break\">in page source (F12 → Elements)
- Look for
-
Verify you're in staff interface:
- Panel only appears for staff members, not in client portal
-
Check signal registration:
- Enable debug mode:
define('SUBTICKET_DEBUG', true); - Check
/tmp/subticket-debug.logfor:Signal registered: object.view for ticket view integration onTicketView() called: Object: Ticket
- Enable debug mode:
¶ Problem: Cannot create subticket
Symptoms:
- Click "Create Subticket" but nothing happens
- Redirected to new ticket form but ticket doesn't link to parent
Check:
-
You have permission to create tickets:
- Admin Panel → Agents → Your Agent → Permissions
- "Create Tickets" should be enabled
-
Parent ticket is not closed:
- Closed tickets should not allow subticket creation (check
tickets.php?a=open&subticket_parent=X)
- Closed tickets should not allow subticket creation (check
-
Check Apache error log:
tail -f /var/log/apache2/error.log -
Session storage issue:
- Check if
$_SESSION['subticket_parent']is set after clicking button - Enable debug logging and check
/tmp/subticket-debug.log:Stored subticket_parent in session: 15 Auto-linking ticket: Child: 456, Parent: 15
- Check if
¶ Problem: Badge appears multiple times
Symptoms:
- Multiple "Parent Ticket (X Sub-Tickets)" badges in ticket view
Solution:
- Update to v1.5.1 or later - This issue was fixed by preventing duplicate panel instances
- After updating, clear browser cache (Ctrl+Shift+R)
If issue persists:
- Check for JavaScript errors in console (may be injecting panel multiple times)
- Verify plugin is not loaded twice (check
include/plugins/for duplicates)
¶ Problem: Circular dependency error when linking
Symptoms:
- Error: "Circular dependency detected"
- Cannot link ticket A to ticket B
Explanation:
The plugin prevents circular dependencies to maintain tree integrity. For example:
- Ticket A is parent of B
- Ticket B is parent of C
- You cannot make Ticket C the parent of A (would create a loop)
Solution:
- Review your ticket hierarchy
- Unlink intermediate relationships if necessary
- Structure tickets in a tree (not a graph)
¶ Problem: Database error on enable
Symptoms:
- Plugin enable fails
- Error: "Table already exists" or "Column already exists"
Check:
-
Check existing tables:
SHOW TABLES LIKE 'ost_ticket_hierarchy_metadata'; SHOW TABLES LIKE 'ost_ticket_progress'; -
Check existing columns:
SHOW COLUMNS FROM ost_ticket LIKE 'version'; -
Plugin already handles duplicates - If enable fails, check Apache error log for specific SQL error
-
Manual cleanup (if needed):
-- CAUTION: Only run if reinstalling! DROP TABLE IF EXISTS ost_ticket_hierarchy_metadata; DROP TABLE IF EXISTS ost_ticket_progress; ALTER TABLE ost_ticket DROP COLUMN IF EXISTS version;
¶ Technical Details
¶ Architecture
Plugin Structure:
subticket-manager/
├── plugin.php # Plugin metadata
├── class.SubticketPlugin.php # Main plugin class
├── config.php # Plugin configuration class
├── queue-decoration.php # Queue SQL enhancement (ParentTicketDecoration)
├── ajax/
│ └── SubticketAjaxAPI.php # AJAX endpoint handlers (legacy)
├── scp-files/
│ ├── subtickets.php # Admin interface page (deployed to scp/)
│ ├── apps.php # Applications overview page
│ └── ajax-subticket.php # Standalone AJAX handler
├── js/
│ ├── subticket-panel.js # Frontend panel interactions
│ └── queue-indicator.js # Queue list parent indicators
├── services/
│ ├── SubticketService.php # Business logic layer
│ └── SubticketCreator.php # Ticket creation service
├── repositories/
│ └── SubticketRelationRepository.php # Database access layer
├── validation/
│ └── SubticketValidator.php # Input validation
├── cache/
│ └── SubticketCacheManager.php # Performance optimization
├── events/
│ └── SubticketEventHandler.php # Signal handlers (auto-close, etc.)
└── tests/
└── Unit/ # PHPUnit tests
Signal Hooks:
| Signal | Handler | Purpose |
|---|---|---|
object.view |
onTicketView() |
Inject panel HTML into ticket view |
model.created |
onTicketCreated() |
Auto-link newly created subtickets |
model.updated |
onTicketStatusChanged() |
Trigger auto-close workflow (Phase 4) |
ajax.scp |
registerAjaxRoutes() |
Register AJAX endpoints (legacy, unused) |
Database Schema:
-- Additional tables created by plugin
CREATE TABLE ost_ticket_hierarchy_metadata (
ticket_id int(11) unsigned PRIMARY KEY,
auto_close_enabled tinyint(1) DEFAULT 1,
inherit_settings text,
dependency_type enum('blocks','depends_on','relates_to') DEFAULT 'relates_to',
max_children int(11) DEFAULT 50,
created timestamp DEFAULT CURRENT_TIMESTAMP,
updated timestamp DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
FOREIGN KEY (ticket_id) REFERENCES ost_ticket(ticket_id) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
CREATE TABLE ost_ticket_progress (
parent_id int(11) unsigned PRIMARY KEY,
total_children int(11) DEFAULT 0,
completed_children int(11) DEFAULT 0,
in_progress_children int(11) DEFAULT 0,
pending_children int(11) DEFAULT 0,
last_calculated timestamp DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
FOREIGN KEY (parent_id) REFERENCES ost_ticket(ticket_id) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
-- Indexes added to ost_ticket
CREATE INDEX idx_ticket_pid ON ost_ticket(ticket_pid);
CREATE INDEX idx_ticket_hierarchy ON ost_ticket(ticket_id, ticket_pid, status_id);
-- Column added to ost_ticket
ALTER TABLE ost_ticket ADD COLUMN version int(11) DEFAULT 0;
¶ Security Features
-
Input Validation:
- All ticket IDs validated as positive integers
db_input()used for SQL escaping (osTicket standard)- CSRF token required for all AJAX requests
-
Circular Dependency Prevention:
isDescendant()method checks ancestry up to 10 levels- Prevents tickets from being their own ancestors
-
Self-Linking Prevention:
- Tickets cannot be linked to themselves
- Checked before database queries
-
Permission Checks:
- Only staff members can access subticket panel
- AJAX endpoints check staff authentication
¶ Performance Optimizations
-
Single Query for Children:
getChildren()uses JOIN to fetch subject and status in one query- Avoids N+1 query problem
-
Queue Indicator Caching:
queue-indicator.jsbatches parent status checks- Single AJAX request for multiple tickets
-
Auto-Deploy Version Check:
- Files only deployed when version changes
- Version tracking via
.subticket-deployed-versionfile
-
Database Indexes:
idx_ticket_pidspeeds up child lookupsidx_ticket_hierarchyoptimizes parent-child queries
¶ FAQ
¶ General Questions
Q: Do I need to modify osTicket core files?
A: No! The plugin uses osTicket's native ticket_pid infrastructure and Signal system. All features work without touching core files.
Q: Will this work with my custom osTicket theme?
A: Yes, the plugin uses osTicket's standard CSS classes and structure. Visual indicators and panels adapt to your theme automatically.
Q: Can I upgrade osTicket without breaking the plugin?
A: Yes, as long as osTicket maintains the ticket_pid field and Signal system (which are core features). The plugin is tested against osTicket 1.18.x.
Q: How do I uninstall the plugin?
A: Admin Panel → Plugins → Subticket Manager → Delete. The plugin will:
- Remove deployed files (
scp/subtickets.php,scp/ajax-subticket.php,scp/apps.php) - Optionally remove database tables (configurable)
- Preserve ticket relationships (data remains in
ticket_pid)
¶ Features & Functionality
Q: What's the maximum hierarchy depth?
A: The plugin supports up to 10 levels of nesting (configurable in isDescendant() method). This prevents infinite loops and maintains performance.
Q: Can a ticket have multiple parents?
A: No. osTicket's ticket_pid field only supports one parent per ticket. This matches the tree structure design.
Q: Can I bulk-link tickets?
A: Yes, use the Subticket Hierarchies admin page (Applications → Subticket Hierarchies) for batch operations.
Q: What happens if I delete a parent ticket?
A: By default, child tickets remain but their ticket_pid is set to NULL (unlinked). If you have foreign key constraints with ON DELETE CASCADE, children would also be deleted.
Q: Does auto-close work immediately?
A: Auto-close is a Phase 4 feature (currently in development). When all child tickets are closed, the parent will automatically close via model.updated signal handler.
¶ Technical Questions
Q: How are parent indicators added to queue lists?
A: The plugin uses two mechanisms:
- Queue Decoration:
ParentTicketDecorationclass extends osTicket'sQueueColumnAnnotationto add a SQL JOIN counting child tickets - JavaScript Injection:
queue-indicator.jsfetches parent status via AJAX and injects icons dynamically
Q: Why use standalone AJAX handler instead of Signal routing?
A: The standalone handler (ajax-subticket.php) is simpler and more maintainable than Signal-based routing. It provides direct, predictable endpoints without complex dispatcher logic.
Q: How does auto-linking work for new subtickets?
A: When you click "Create Subticket", the parent ID is stored in $_SESSION['subticket_parent']. After the ticket is created, the model.created signal handler (onTicketCreated()) automatically sets ticket_pid in the database.
Q: Can I customize the panel appearance?
A: Yes, modify getPanelCSS() method in class.SubticketPlugin.php. All styles are inline CSS for easy customization.
Q: How do I enable debug logging?
A: Edit class.SubticketPlugin.php and change line 8:
define('SUBTICKET_DEBUG', true);
Debug logs are written to /tmp/subticket-debug.log.
Q: What SQL queries are executed?
A: Enable debug mode and check /tmp/subticket-debug.log. Example queries:
-- Get children
SELECT t.ticket_id, t.number, cdata.subject, s.name as status
FROM ost_ticket t
LEFT JOIN ost_ticket__cdata cdata ON t.ticket_id = cdata.ticket_id
LEFT JOIN ost_ticket_status s ON t.status_id = s.id
WHERE t.ticket_pid = 15;
-- Link ticket
UPDATE ost_ticket SET ticket_pid = 15 WHERE ticket_id = 123;
¶ Compatibility
Q: Does this work with osTicket 1.17 or older?
A: No. The plugin requires osTicket 1.18.x for proper Signal support and database structure. osTicket 1.17 and older may have different ticket_pid implementations.
Q: Is it compatible with PHP 8.x?
A: Yes! The plugin is tested with PHP 7.4, 8.0, 8.1, 8.2, and 8.3. CI pipeline runs tests on all versions.
Q: Can I use this with PostgreSQL instead of MySQL?
A: The plugin is designed for MySQL/MariaDB. PostgreSQL support would require modifying SQL queries (osTicket itself primarily supports MySQL).
Q: Does it work with Elasticsearch queue plugin?
A: Should work, but not explicitly tested. The queue decoration hooks into osTicket's standard queue system, so Elasticsearch plugins may override it.
¶ 📄 License
This Plugin is released under the GNU General Public License v2, compatible with osTicket core.
See LICENSE for details.
¶ 💬 Support
For questions or issues, please create an issue on GitHub:
Issue Tracker: https://github.com/markus-michalski/osticket-subticket-manager/issues
When reporting issues, please include:
- osTicket version (Admin Panel → Settings → About)
- PHP version (
php -v) - Plugin version
- Browser console errors (F12 → Console)
- Steps to reproduce
¶ 🤝 Contributing
Developed by Markus Michalski
Contributions welcome!
- Fork the repository
- Create a feature branch
- Submit a pull request
¶ Changelog
See CHANGELOG.md for version history.