Concepts
Troubleshooting
Common issues with pre-built connectors and step-by-step solutions to debug integration problems.
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 impact
- P2 (High): Partial failure, workaround available
- P3 (Medium): Minor issue, low impact
- P4 (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
