Halo PSA Troubleshooting

Previous

Common issues and solutions for Halo PSA integration with SuperIT

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

Authentication and Connection Issues

Authentication Failures

Symptoms:

  • "Authentication failed" error during connection setup
  • "Invalid client credentials" messages
  • Connection status shows "Failed" or "Unauthorized"

Solutions:

Verify API Application Settings
  1. Check Client Credentials: Ensure Client ID and Secret are copied correctly
  2. Application Status: Ensure the Super IT API application is set to Active in Halo PSA
  3. Authentication Method: Confirm the application uses Client ID and Secret (Services)
  4. Login Agent: Confirm the application's "Agent to log in as" is set to the dedicated Super IT agent, and that agent is active
Regenerate Credentials
  1. Client Secret: If the secret was lost or is suspected to be compromised, generate a new one from the application's configuration page
  2. Update SuperIT: Enter the new Client ID/Secret in the SuperIT connection settings
  3. Re-test: Run Save & Test on the connection to confirm authentication succeeds

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 Application Permissions
  1. Check Scopes: Verify the API application has all required scopes:
    • all:teams, admin:webhooks
    • read:tickets, edit:tickets
    • read:customers, read:assets
  2. Application Status: Confirm the application is active in Halo PSA
  3. Update Scopes: Add any missing scopes on the application's Permissions tab and save
Review Agent Permissions
  1. Feature Access: Confirm the Super IT agent's ticket, customer, and asset access levels match what's needed
  2. Ticket Permissions: Verify "Can add new tickets," "Can view unassigned tickets," and "Can view tickets assigned to other agents" are enabled
  3. Type Restrictions: Check asset type and ticket type restrictions aren't excluding needed data
  4. Data Access: Verify the agent can access all required data in Halo PSA

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 SuperIT
  • Client count doesn't match Halo PSA
  • Client information incomplete

Solutions:

Permission and Access Issues
  1. Client Visibility: Verify the Super IT agent 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 SuperIT
  • Incomplete ticket information
  • Sync shows errors or warnings
  • Old tickets missing

Solutions:

Ticket Access Permissions
  1. Ticket Visibility: Confirm the Super IT agent 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 the Super IT agent 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 SuperIT 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 SuperIT
  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 SuperIT
  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 SuperIT
  • 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:

    • Check Halo PSA service status
    • Verify network connectivity
    • Test API credentials manually
    • Review recent configuration changes

  2. Service Restoration:

    • Regenerate and update the Client Secret if needed
    • Recreate webhook endpoints
    • Restart sync processes
    • Verify data integrity

  3. Fallback Procedures:

    • Use Halo PSA directly for urgent issues
    • Implement manual ticket routing temporarily
    • Communicate status to affected teams
    • 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

  • SuperIT Support: Access through SuperIT 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
  • Rotate the Client Secret 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 SuperIT support through the dashboard or reference Halo PSA documentation for platform-specific questions.

Halo PSA Webhook Setup