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:
- Check OAuth token expiry
- Verify Connected App settings in Salesforce
- Confirm callback URL is correctly configured
- Re-authorize if refresh token has expired
Insufficient permissions
Symptoms:
- Partial sync failures
- "INSUFFICIENT_ACCESS" errors
Resolution:
- Review Salesforce user's profile permissions
- Verify object-level and field-level security
- 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:
- Check Salesforce duplicate management settings
- Review field mapping configuration
- Check Salesforce validation rules on Contact object
- 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:
- Compare field mapping with current Salesforce schema
- Verify picklist values exist in Salesforce
- 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:
- Review sync timestamps for both systems
- Check conflict resolution configuration
- 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:
- Verify activity sync is enabled in settings
- Check Salesforce activity history retention
- 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:
- Collect organization ID, Salesforce org ID, error details
- Review Salesforce debug logs if available
- Check Salesforce Trust status for service issues
- Escalate to development team with full diagnostic output