PSA/docs/archive/itil-consolidation-cleanup-plan.md

ITIL Consolidation Cleanup Plan

Date: 2025-09-18 Issue: Incomplete consolidation, cleanup needed

Original Implementation Plan (From Previous Claude)

🎯 Design Decision Summary

• ITIL remains rigid - no user modifications allowed
• Per-board configuration - each channel chooses custom OR ITIL (not tenant-level)
• Full consolidation - migrate ITIL data to standard priority/category tables
• Immediate implementation - go straight to consolidation (no interim fixes)

📋 Original Implementation Plan

Phase 1: Create ITIL Standard Records

1.1 ITIL Priority Records Create migration to populate standard_priorities table with ITIL standards:

-- 5 ITIL priority records (GLOBAL, not per tenant)
INSERT INTO standard_priorities (priority_id, priority_name, color, order_number, is_itil_standard, item_type, itil_priority_level)
VALUES
  (uuid(), 'Critical', '#EF4444', 1, true, 'ticket', 1),
  (uuid(), 'High', '#F97316', 2, true, 'ticket', 2),
  (uuid(), 'Medium', '#EAB308', 3, true, 'ticket', 3),
  (uuid(), 'Low', '#3B82F6', 4, true, 'ticket', 4),
  (uuid(), 'Planning', '#6B7280', 5, true, 'ticket', 5);

1.2 ITIL Category Records Create migration to populate standard_categories table with ITIL tree:

-- Parent categories: Hardware, Software, Network, Security, Service Request
-- Child categories: Server, Application, VPN, Malware, Access Request, etc.
-- Mark all with is_itil_standard: true

Phase 2: Update Channel Configuration

• Add ITIL capability flags to standard_channels and channels tables
• Modify channel priority/category type validation
• Ensure channels using ITIL only reference ITIL standard records
• Add UI warnings if ITIL standards are attempted to be modified

Phase 3: Update ITIL Components

3.1 Impact × Urgency Calculation

• Keep existing calculation logic in UI components
• Map calculated priority level (1-5) to corresponding ITIL priority record ID
• Store in standard priority_id field instead of itil_priority_level

3.2 Category Selection

• ItilFields, TicketInfo, QuickAddTicket already use CategoryPicker
• Update to use ITIL records from categories table instead of hardcoded ItilCategories
• Filter CategoryPicker to show only ITIL records when channel uses ITIL

Phase 4: Database Schema Updates

4.1 Add ITIL Standard Flags

-- Add to standard_priorities table (NOT per tenant)
ALTER TABLE standard_priorities ADD COLUMN is_itil_standard BOOLEAN DEFAULT false;
ALTER TABLE standard_priorities ADD COLUMN itil_priority_level INTEGER; -- 1-5 mapping

-- Add to standard_categories table (NOT per tenant)
ALTER TABLE standard_categories ADD COLUMN is_itil_standard BOOLEAN DEFAULT false;

-- Add ITIL capability flags to channels
ALTER TABLE channels ADD COLUMN supports_itil_priorities BOOLEAN DEFAULT false;
ALTER TABLE channels ADD COLUMN supports_itil_categories BOOLEAN DEFAULT false;

-- Add ITIL capability flags to standard_channels
ALTER TABLE standard_channels ADD COLUMN supports_itil_priorities BOOLEAN DEFAULT false;
ALTER TABLE standard_channels ADD COLUMN supports_itil_categories BOOLEAN DEFAULT false;

4.2 Migration Script for Existing Tickets SKIPPED - No tickets with ITIL in production (branch not published yet)

Phase 5: Update Business Logic

5.1 Ticket Creation/Updates

• Remove dual priority/category handling
• Always use priority_id and category_id
• For ITIL channels: map Impact×Urgency to ITIL priority record ID

5.2 Filtering & Queries

• Remove dual filtering logic from optimizedTicketActions.ts
• All tickets now filter by standard priority_id and category_id
• ITIL tickets appear in filters automatically (same table, same fields)

5.3 Display Logic

• Update ticket-columns.tsx to remove ITIL-specific display paths
• All tickets use same priority/category display logic
• ITIL calculation details (Impact×Urgency) remain in ticket details

Phase 6: Cleanup

6.1 Remove Redundant Fields After migration validation:

-- Remove old ITIL fields from tickets table
ALTER TABLE tickets DROP COLUMN itil_priority_level;
ALTER TABLE tickets DROP COLUMN itil_category;
ALTER TABLE tickets DROP COLUMN itil_subcategory;

6.2 Remove Hardcoded ITIL Data

• Remove ItilCategories object from utils
• Remove hardcoded priority mapping logic
• Keep ItilLabels for Impact/Urgency display only

User Feedback on Original Plan

• Step 4.2 not necessary - no tickets with ITIL in production (branch has not been published)
• Migration files can be edited - they were rolled back, so direct editing is possible
• Step 1.1 - priorities should not be per tenant, add them to standard_priorities to make ITIL available for import
• 4.1 Add ITIL Standard Flags - these should go to standard_priorities, standard_categories (not tenant tables)
• Need ITIL capability flags - add to both standard_channels and channels tables

---

Post-Implementation Assessment

Date: 2025-09-18 Status: Plan approximately 70% completed - significant cleanup work remains

✅ What Was Successfully Implemented:

Database Schema Updates:

• ✅ Added ITIL flags to standard_priorities, standard_categories, standard_channels, and channels tables
• ✅ ITIL priorities added to standard_priorities table with proper mapping
• ✅ ITIL categories added to standard_categories table
• ✅ Removed redundant itil_category, itil_subcategory, and itil_priority_level fields from tickets table migration
• ✅ Priority calculation and mapping logic updated in ticketActions.ts
• ✅ Priority display logic consolidated in ticket-columns.tsx

Business Logic:

• ✅ Updated optimizedTicketActions.ts to fetch both custom and ITIL priorities/categories
• ✅ Priority calculation maps ITIL Impact×Urgency to correct standard_priorities record

❌ Why The Plan Was Not Fully Executed:

The implementation stopped at the database/backend level but did not complete the frontend component cleanup. Many files still reference the deprecated fields that should have been removed:

• itil_priority_level - found in 15+ files
• itil_category - found in 20+ files
• itil_subcategory - found in 15+ files

Root Cause: The original implementation focused on making the new system work alongside the old system, but did not complete the removal of the old system, leaving a dual-system approach instead of true consolidation.

---

Completion Plan - Remaining Work

The following phases will complete the ITIL consolidation by removing all legacy dual-system references and fully implementing the unified priority/category system.

Phase 1: Interface & Schema Cleanup (High Priority)

1.1 Update Ticket Interfaces

• File: server/src/interfaces/ticket.interfaces.tsx
• Remove deprecated fields from ITicket interface: itil_priority_level, itil_category, itil_subcategory
• Update comment on priority_id to reflect unified system
• Update ITicketListItem interface accordingly

1.2 Update Ticket Schemas

• File: server/src/lib/schemas/ticket.schema.ts
• Remove from ticketFormSchema: itil_priority_level, itil_category, itil_subcategory
• Remove validation rule requiring priority_id OR itil_priority_level
• Remove corresponding fields from ticketSchema and ticketUpdateSchema

1.3 Update Channel Interface

• File: server/src/interfaces/channel.interface.ts
• Remove display_itil_category field if no longer needed

Phase 2: Component Logic Updates (Critical)

2.1 Modernize ItilFields Component

• File: server/src/components/tickets/ItilFields.tsx
• Remove hardcoded ItilCategories import and usage
• Update to receive ITIL categories as props from parent components
• Remove category/subcategory selection logic (use unified CategoryPicker)
• Keep only Impact/Urgency fields and resolution fields

2.2 Complete QuickAddTicket Updates

• File: server/src/components/tickets/QuickAddTicket.tsx
• Remove all references to itil_category and itil_subcategory
• Remove hardcoded category handling logic
• Ensure ITIL categories are properly filtered from unified categories list

2.3 Complete TicketInfo Updates

• File: server/src/components/tickets/ticket/TicketInfo.tsx
• Remove legacy ITIL category handling
• Ensure category changes go through unified category system only

2.4 Update TicketDetails Component

• File: server/src/components/tickets/ticket/TicketDetails.tsx
• Remove separate ITIL category state management
• Remove legacy field handling in update logic
• Ensure all category/priority updates use unified system

Phase 3: Business Logic Cleanup (Medium Priority)

3.1 Update Service Layer

• File: server/src/lib/services/itilService.ts
• Update category references to use category_id
• Modify metrics collection to work with unified category system

3.2 Update Workflow Logic

• File: server/src/lib/workflows/itilIncidentLifecycleWorkflow.ts
• Update category validation to use unified category system

3.3 Clean Up Remaining Components

• Update any remaining files with legacy field references
• Ensure all ticket queries only use unified fields

Phase 4: Testing & Validation (Critical)

4.1 Functional Testing

• Test ITIL ticket creation with Impact/Urgency calculation
• Verify ITIL categories display correctly in CategoryPicker
• Confirm priority mapping works correctly
• Test ticket updates maintain ITIL functionality

4.2 Database Verification

• Confirm no code references removed database fields
• Verify ITIL priorities/categories are properly loaded from standard tables

Success Criteria

✅ No references to itil_priority_level, itil_category, itil_subcategory in codebase ✅ All ITIL tickets use unified priority_id and category_id fields ✅ ITIL Impact/Urgency calculation still works and maps to correct priorities ✅ ITIL categories display correctly using unified CategoryPicker ✅ All tests pass and ITIL functionality is preserved