¶ Subticket Manager
Live Demo: Try all plugins for OXID eShop, Shopware and osTicket by Markus Michalski live — no installation, no risk. demo.markus-michalski.net
¶ 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}
}
¶ 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
- Verify jQuery is loaded:
typeof jQuery // Should return "function" - Enable debug mode:
SubticketPanel.debug = true - Check AJAX endpoint:
curl "http://osticket.local/scp/ajax-subticket.php?action=batch_parent_status&ticket_ids=15"
¶ 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
- Clear browser cache
- Verify you're in staff interface - Panel only appears for staff members
- Check signal registration - Enable debug mode and check
/tmp/subticket-debug.log
¶ Problem: Cannot create subticket
Symptoms:
- Click "Create Subticket" but nothing happens
Check:
- You have permission to create tickets
- Parent ticket is not closed
- Check Apache error log:
tail -f /var/log/apache2/error.log
¶ Problem: Circular dependency error when linking
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 and restructure as needed.
¶ 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
├── scp-files/ # Files deployed to scp/
├── js/ # Frontend JavaScript
├── services/ # Business logic layer
├── repositories/ # Database access layer
├── validation/ # Input validation
├── cache/ # Performance optimization
├── events/ # Signal handlers
└── tests/ # 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) |
¶ Security Features
- Input Validation - All ticket IDs validated as positive integers, CSRF tokens required
- Circular Dependency Prevention -
isDescendant()checks ancestry up to 10 levels - Self-Linking Prevention - Tickets cannot be linked to themselves
- Permission Checks - Only staff members can access subticket panel
¶ Performance Optimizations
- Single Query for Children - JOIN to fetch subject and status in one query
- Queue Indicator Caching - Batched AJAX requests for multiple tickets
- Database Indexes -
idx_ticket_pidandidx_ticket_hierarchyfor fast lookups
¶ 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.
Q: Can I upgrade osTicket without breaking the plugin?
A: Yes, as long as osTicket maintains the ticket_pid field and Signal system.
Q: What's the maximum hierarchy depth?
A: Up to 10 levels of nesting (configurable).
Q: Can a ticket have multiple parents?
A: No. osTicket's ticket_pid field only supports one parent per ticket.
¶ Compatibility
Q: Does this work with osTicket 1.17 or older?
A: No. The plugin requires osTicket 1.18.x.
Q: Is it compatible with PHP 8.x?
A: Yes! Tested with PHP 7.4, 8.0, 8.1, 8.2, and 8.3.
¶ 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.