Halo PSA Troubleshooting

Previous

Common issues and solutions for Halo PSA integration with Super IT

This guide covers common issues you might encounter with Halo PSA integration and provides step-by-step solutions.

Authentication and Connection Issues

OAuth Authorization Failures

Symptoms: - "Authorization failed" error during connection setup - Unable to complete OAuth flow - "Invalid client credentials" messages - Connection status shows "Failed" or "Unauthorized"

Solutions:

Verify OAuth Application Settings
  1. Check Client Credentials: Ensure Client ID and Secret are copied correctly
  2. Verify Redirect URI: Confirm redirect URI matches Super IT callback URL exactly
  3. Review Permissions: Check OAuth application has required scopes enabled
  4. Application Status: Ensure OAuth application is active in Halo PSA
Test OAuth Flow Manually
  1. Browser Test: Try OAuth authorization in incognito/private browser
  2. Clear Cache: Clear browser cache and cookies for Halo PSA domain
  3. Admin Rights: Ensure user has admin rights to authorize applications
  4. Alternative User: Try OAuth flow with different admin user

API Permission Errors

Symptoms: - "Insufficient permissions" during sync operations - 403 Forbidden errors in sync logs - Some data syncs but others fail - Partial client or ticket information

Solutions:

Review API Permissions
  1. Check Scopes: Verify OAuth application has all required scopes:
  2. read:tickets, write:tickets
  3. read:clients, read:assets
  4. read:users, write:webhooks
  5. Admin Permissions: Confirm authorizing user has admin access
  6. Data Access: Verify user can access all required data in Halo PSA
  7. Re-authorize: Try re-authorizing OAuth application with updated permissions

Connection Timeout Issues

Symptoms: - Connection test times out - Intermittent sync failures - Webhook delivery failures - "Connection refused" errors

Solutions:

Network Configuration
  1. Firewall Rules: Ensure outbound HTTPS (443) access to Halo PSA
  2. Proxy Settings: Configure proxy settings if required
  3. DNS Resolution: Verify Halo PSA URL resolves correctly
  4. SSL/TLS: Ensure TLS 1.2+ support for secure connections
Halo PSA Server Status
  1. Service Status: Check Halo PSA status page for outages
  2. Maintenance Windows: Verify no scheduled maintenance
  3. Rate Limiting: Check if API rate limits are being exceeded
  4. Instance Health: Contact Halo support if persistent issues

Sync Issues

Client Sync Problems

Symptoms: - No clients appear after sync - Missing clients in Super IT - Client count doesn't match Halo PSA - Client information incomplete

Solutions:

Permission and Access Issues
  1. Client Visibility: Verify OAuth user can see all clients in Halo PSA
  2. Client Status: Check if inactive clients are filtered out
  3. Data Validation: Ensure clients have required fields populated
  4. Batch Size: Try reducing sync batch size for large client lists
Sync Configuration
  1. Sync Filters: Review any active client filtering settings
  2. Date Range: Check if date filters are excluding clients
  3. Manual Retry: Try manual client sync with debug logging
  4. Incremental Sync: Use incremental rather than full sync

Ticket Sync Failures

Symptoms: - Tickets not appearing in Super IT - Incomplete ticket information - Sync shows errors or warnings - Old tickets missing

Solutions:

Ticket Access Permissions
  1. Ticket Visibility: Confirm OAuth user can access all required tickets
  2. Client Access: Verify user has access to all client tickets
  3. Status Filters: Check if certain ticket statuses are excluded
  4. Board Access: Ensure access to all relevant service boards
Data Volume Management
  1. Date Range: Limit initial sync to recent tickets (last 30-90 days)
  2. Client Filter: Sync one client at a time for troubleshooting
  3. Batch Size: Reduce ticket sync batch size
  4. Status Filter: Sync open tickets first, then closed tickets

Asset Sync Issues

Symptoms: - Assets not syncing from Halo PSA - Incomplete asset information - Asset relationships missing - Performance issues during asset sync

Solutions:

Asset Permission Check
  1. Asset Access: Verify OAuth user can view assets in Halo PSA
  2. Client Assets: Confirm access to assets for all linked clients
  3. Asset Types: Check if certain asset types are excluded
  4. Inactive Assets: Verify whether inactive assets should sync
Asset Sync Optimization
  1. Selective Sync: Sync only active or deployed assets initially
  2. Asset Types: Choose specific asset types to sync
  3. Location Filter: Limit sync to specific locations
  4. Batch Processing: Use smaller batches for large asset inventories

Webhook Issues

Webhook Registration Problems

Symptoms: - Unable to create webhooks in Halo PSA - Webhook endpoints not accessible - "Invalid URL" errors - Webhook creation succeeds but events don't fire

Solutions:

Webhook Configuration
  1. URL Accessibility: Verify webhook URL is publicly accessible
  2. SSL Certificate: Ensure valid SSL certificate on webhook endpoint
  3. Firewall Rules: Allow Halo PSA server access to webhook URL
  4. HTTP Method: Confirm webhook endpoint accepts POST requests
Halo PSA Webhook Settings
  1. Event Types: Verify correct event types are selected
  2. Object Types: Ensure relevant object types are configured
  3. Authentication: Check webhook secret configuration
  4. Payload Format: Confirm JSON payload format is selected

Webhook Delivery Failures

Symptoms: - Webhooks created but not firing - Delayed webhook delivery - Missing webhook events - Inconsistent event delivery

Solutions:

Webhook Monitoring
  1. Delivery Logs: Check Super IT webhook receipt logs
  2. Halo PSA Logs: Review Halo webhook delivery logs (if available)
  3. Network Timing: Monitor webhook delivery timing
  4. Payload Validation: Verify webhook payload format
Delivery Troubleshooting
  1. Test Webhooks: Use Halo's webhook test feature
  2. Manual Testing: Create test events to trigger webhooks
  3. Network Path: Trace network path from Halo to Super IT
  4. Rate Limiting: Check if webhooks are being rate limited

Performance Issues

Slow Sync Performance

Symptoms: - Sync operations take excessive time - Timeouts during large data syncs - System becomes unresponsive - Memory usage spikes during sync

Solutions:

Sync Optimization
  1. Batch Size: Reduce sync batch size for better performance
  2. Parallel Processing: Limit concurrent sync operations
  3. Date Filtering: Sync smaller date ranges
  4. Selective Sync: Sync only necessary data types
System Resources
  1. Memory Usage: Monitor memory consumption during sync
  2. Network Bandwidth: Check network utilization
  3. Halo PSA Load: Verify Halo PSA isn't overloaded
  4. Database Performance: Monitor database query performance

Webhook Performance Issues

Symptoms: - Webhook delivery delays - Webhook queue backup - High webhook failure rate - Inconsistent webhook timing

Solutions:

Webhook Optimization
  1. Event Filtering: Reduce unnecessary webhook events
  2. Endpoint Performance: Optimize webhook endpoint processing
  3. Network Latency: Check network latency between systems
  4. Queue Management: Monitor webhook queue status

Data Quality Issues

Incomplete or Missing Data

Symptoms: - Ticket data doesn't match Halo PSA - Missing custom fields - Incorrect client assignments - Missing asset relationships

Solutions:

Data Validation
  1. Field Mapping: Verify all required fields are syncing
  2. Character Encoding: Check for character encoding issues
  3. Data Types: Ensure data types match between systems
  4. Null Handling: Verify how empty values are processed
Sync Verification
  1. Record Comparison: Compare records between Halo PSA and Super IT
  2. Audit Logs: Check sync audit logs for data transformation
  3. Error Analysis: Review detailed error logs
  4. Selective Resync: Resync specific records to verify accuracy

Duplicate Records

Symptoms: - Same client appears multiple times - Duplicate tickets in Super IT - Inconsistent record counts - Data integrity issues

Solutions:

Deduplication
  1. Unique Identifiers: Verify unique ID handling is working
  2. Sync Logic: Check sync logic for duplicate prevention
  3. Data Cleanup: Remove duplicate records manually
  4. Prevention: Adjust sync settings to prevent future duplicates

Team Management Issues

Client Routing Problems

Symptoms: - Tickets routed to wrong teams - Some tickets not routing at all - Team assignments inconsistent - Client links not working

Solutions:

Link Configuration
  1. Client Links: Verify client-team links are active
  2. Team Permissions: Ensure teams can receive tickets
  3. Routing Rules: Check conditional routing configuration
  4. Default Teams: Verify default team assignments
Testing Routing
  1. Test Tickets: Create test tickets to verify routing
  2. Manual Assignment: Test manual ticket assignment
  3. Bulk Operations: Test bulk client linking
  4. Error Logging: Check routing error logs

Emergency Procedures

Complete Integration Failure

If Halo PSA integration completely fails:

  1. Immediate Assessment:
  2. Check Halo PSA service status
  3. Verify network connectivity
  4. Test OAuth credentials manually

  5. Review recent configuration changes

  6. Service Restoration:

  7. Re-authorize OAuth connection if needed
  8. Recreate webhook endpoints
  9. Restart sync processes

  10. Verify data integrity

  11. Fallback Procedures:

  12. Use Halo PSA directly for urgent issues
  13. Implement manual ticket routing temporarily
  14. Communicate status to affected teams
  15. Document issues for post-incident review

Data Recovery

If data synchronization issues cause data loss:

  1. Stop Sync Operations: Prevent further data corruption
  2. Assess Impact: Determine scope of affected data
  3. Backup Restoration: Restore from backup if available
  4. Manual Sync: Manually sync critical records
  5. Verification: Verify data integrity before resuming

Escalation Procedures

When to contact support:

Immediate Escalation: - Complete sync failure affecting all operations - Data corruption or loss detected - Security issues or unauthorized access - System completely unresponsive

Standard Support: - Intermittent sync issues - Performance degradation - Configuration questions - Feature enhancement requests

Contact Information

  • Super IT Support: Access through Super IT dashboard
  • Halo PSA Support: Through Halo PSA support portal
  • Emergency Procedures: Use established escalation procedures
  • Documentation: Reference integration documentation

Prevention and Monitoring

Proactive Monitoring

Daily Checks: - Review sync status indicators - Check webhook delivery health - Monitor error logs for new issues - Verify team routing accuracy

Weekly Analysis: - Analyze sync performance trends - Review client link effectiveness - Check data quality metrics - Update configuration as needed

Monthly Audits: - Compare data between systems - Review security and access permissions - Update OAuth credentials as needed - Plan for Halo PSA updates

Performance Metrics

Key Indicators: - Sync success rates - Average sync duration - Webhook delivery rates - Error frequency and types - Team routing accuracy

Alert Configuration: - Sync failure notifications - Performance threshold alerts - Security event monitoring - Data quality warnings

Still experiencing issues? Contact Super IT support through the dashboard or reference Halo PSA documentation for platform-specific questions.

Halo PSA Webhook Setup