Salesforce Troubleshooting

Diagnose and resolve Salesforce CRM integration issues

Platform administrators can diagnose and assist with Salesforce integration issues.

Common Issues

Authentication & Connection

OAuth authentication failures

Symptoms:

• Integration shows “disconnected”
• 401 Unauthorized errors in sync logs

Resolution:

1. Check OAuth token expiry
2. Verify Connected App settings in Salesforce
3. Confirm callback URL is correctly configured
4. Re-authorize if refresh token has expired

Insufficient permissions

Symptoms:

• Partial sync failures
• “INSUFFICIENT_ACCESS” errors

Resolution:

1. Review Salesforce user’s profile permissions
2. Verify object-level and field-level security
3. Check sharing rules for relevant records

Data Sync Issues

Contacts not syncing

Common causes:

• Duplicate rules blocking insert
• Required fields not mapped
• Validation rules failing

Troubleshooting:

1. Check Salesforce duplicate management settings
2. Review field mapping configuration
3. Check Salesforce validation rules on Contact object
4. Review sync error logs for specific field errors

Field mapping errors

Common causes:

• Picklist value not in Salesforce
• Data type mismatch
• Field no longer exists

Troubleshooting:

1. Compare field mapping with current Salesforce schema
2. Verify picklist values exist in Salesforce
3. Check for recent Salesforce schema changes

Bidirectional sync conflicts

Common causes:

• Record modified in both systems
• Sync timing causing overwrites
• Missing conflict resolution rules

Troubleshooting:

1. Review sync timestamps for both systems
2. Check conflict resolution configuration
3. Identify which system should be source of truth

Activity Tracking Issues

Activities not appearing

Common causes:

• Task/Event creation disabled
• Activity history limits reached
• Activity type not configured

Troubleshooting:

1. Verify activity sync is enabled in settings
2. Check Salesforce activity history retention
3. Review activity type mapping

Diagnostic Endpoints

Connection Status

GET /api/admin/integrations/salesforce/{organization_id}/status
Authorization: Bearer {admin_token}

Response:

{
  "connected": true,
  "instance_url": "https://na123.salesforce.com",
  "api_version": "59.0",
  "token_expires_at": "2025-01-15T16:00:00Z",
  "last_sync": "2025-01-15T10:30:00Z",
  "sync_stats": {
    "contacts_synced": 1523,
    "contacts_failed": 12,
    "activities_synced": 8934,
    "last_full_sync": "2025-01-10T00:00:00Z"
  }
}

View Sync Errors

GET /api/admin/integrations/salesforce/{organization_id}/errors
Authorization: Bearer {admin_token}

Response:

{
  "errors": [
    {
      "id": "err-uuid-1",
      "type": "contact_sync",
      "salesforce_error": "DUPLICATES_DETECTED",
      "record_id": "member-uuid",
      "details": "Duplicate contact found with matching email",
      "timestamp": "2025-01-15T09:15:00Z",
      "retry_count": 2
    }
  ],
  "total": 12,
  "page": 1
}

Retry Failed Records

POST /api/admin/integrations/salesforce/{organization_id}/retry
Authorization: Bearer {admin_token}
Content-Type: application/json

{
  "error_ids": ["err-uuid-1", "err-uuid-2"]
}

Test Field Mapping

POST /api/admin/integrations/salesforce/{organization_id}/test-mapping
Authorization: Bearer {admin_token}
Content-Type: application/json

{
  "object_type": "Contact",
  "sample_record_id": "member-uuid"
}

Escalation

For complex Salesforce issues:

1. Collect organization ID, Salesforce org ID, error details
2. Review Salesforce debug logs if available
3. Check Salesforce Trust status for service issues
4. Escalate to development team with full diagnostic output