Concepts
Troubleshooting Common issues with pre-built connectors and step-by-step solutions to debug integration problems.
Not Syncing Partial Data Errors Performance
Work orders not creating or updating?
Verify webhook triggering in external system:
Check webhook configuration
Review webhook logs/history
Test webhook manually
Confirm credentials are valid:
API keys not expired
OAuth tokens refreshed
Correct instance/account ID
Sufficient permissions
Check Integration Broker logs:
Navigate to Integrations → Logs
Filter by date/time of expected sync
Look for authentication or validation errors
Trigger a test sync:
Create a simple test record
Verify it meets trigger conditions
Monitor logs for processing
Some fields syncing, others not?
Review configured mappings:
Is the field mapped?
Is the mapping action correct?
Does source field exist in payload?
Ensure API user can access fields:
Read permission on source fields
Write permission on target fields
Custom field API access enabled
Inspect actual data:
Check source field contains value
Verify data type matches expectation
Test transformation logic with sample data
Look for field-specific errors:
Validation failures
Type conversion errors
JSONNET execution errors
Seeing errors in logs?
Determine error type:
Authentication (401, 403)
Validation (400, 422)
Rate Limiting (429)
Server Error (500, 502, 503)
Review error message and context:
Which API endpoint failed?
What data was being sent?
Is error consistent or intermittent?
Follow category-specific fix:
Authentication → Refresh credentials
Validation → Fix field mappings
Rate Limit → Add delays/batching
Server Error → Retry, contact support
Verify fix resolves issue:
Trigger test sync
Watch for successful processing
Confirm no new errors
Syncs are slow or delayed?
Review message queue status:
Navigate to Integrations → Metrics
Check pending message count
Identify bottlenecks
Review external API performance:
Check Integration Broker logs for latency
Test external API directly
Verify no rate limiting
Reduce transformation complexity:
Simplify custom JSONNET
Remove unnecessary field mappings
Batch operations where possible
If consistently slow:
Contact Field Nation Support
Request additional worker instances
Review architecture with support team
Use this systematic approach for any integration issue:
☐ When did the issue start?
☐ Is it affecting all syncs or specific records?
☐ What changed recently? (configuration, external system, Field Nation)
☐ Can you reproduce the issue?
☐ Integration Broker logs for error messages
☐ External system webhook logs
☐ Field Nation work order history
☐ Network/firewall logs if connectivity suspected
☐ Test authentication (API credentials work?)
☐ Test webhook (manual trigger works?)
☐ Test field mappings (with sample data)
☐ Test external API directly (outside integration)
☐ Is it authentication, validation, or transformation?
☐ Is it specific field or all fields?
☐ Is it inbound, outbound, or both?
☐ Is it consistent or intermittent?
☐ Update configuration based on findings
☐ Test fix with sample sync
☐ Monitor for successful processing
☐ Document solution for future reference
Gather this information to expedite support:
Integration Details
Connector name (Salesforce, ServiceNow, etc.)
Company ID
Environment (Sandbox or Production)
Issue Description
What you expected to happen
What actually happened
When the issue started
Frequency (always, sometimes, once)
Relevant IDs
Work Order ID(s) affected
External Record ID(s)
Correlation ID(s)
Error message timestamps
Troubleshooting Attempted
Steps you've already tried
Results of each attempt
Any temporary workarounds
Field Nation Support:
Priority Levels:
P1 (Critical) : Integration completely down, business impactP2 (High) : Partial failure, workaround availableP3 (Medium) : Minor issue, low impactP4 (Low) : Question, enhancement request
Complete support resources →
Each platform has unique considerations:
View all platforms →
✅ Set up error email notifications
✅ Monitor queue depths daily
✅ Review sync success rates weekly
✅ Check external API health
✅ Test integrations after external system upgrades
✅ Rotate API credentials periodically
✅ Review and update field mappings
✅ Document configuration changes
✅ Start simple, add complexity gradually
✅ Test thoroughly in sandbox before production
✅ Keep transformation logic simple
✅ Use descriptive names for mappings
✅ Document business logic in JSONNET comments
