Overview
Neon CRM Integration Nuances
Important behaviors, limitations, and considerations for the WeGive Neon CRM integration
Integration Nuances
Understanding the specific behaviors and considerations of the WeGive Neon CRM integration ensures optimal performance and helps avoid common pitfalls during implementation and ongoing use.
Data Synchronization Behavior
Account Creation Logic
Individual vs Organization Accounts
- Individual Accounts: Created for donors with first/last names
- Company Accounts: Created for donors identified as organizations
- Automatic Detection: Account type determined by donor type in WeGive
- Contact Assignment: Primary contact automatically assigned to accounts
Duplicate Prevention
- Email Matching: Primary matching criterion for existing accounts
- Name + Address: Secondary matching for accounts without email
- Neon ID Tracking: Correlation IDs prevent duplicate creation
- Conflict Resolution: Manual review required for ambiguous matches
Transaction Synchronization
Payment Processing
- Payment Creation: Payments created only for new donations in Neon CRM
- Payment Updates: Existing payments not modified to prevent processing conflicts
- Payment Methods: Proper mapping of WeGive payment types to Neon tender types
- Fee Handling: Donor-covered fees properly attributed in Neon CRM
Transaction Timing
- Creation Date: WeGive creation date preserved in Neon CRM
- Received Date: Mapped to payout date when available
- Processing Order: Transactions processed in chronological order
- Batch Efficiency: Large transaction sets processed in optimized batches
API Rate Limiting and Performance
Neon CRM API Limits
- Request Rate: Standard rate limiting enforced by Neon CRM
- Batch Operations: Optimized batch endpoints used when available
- Retry Logic: Automatic retry with exponential backoff for rate limit hits
- Peak Usage: Consider API usage during high-traffic periods
Performance Optimization
- Incremental Sync: Only changed records synchronized after initial import
- Pagination: Large data sets processed with appropriate pagination
- Parallel Processing: Non-dependent operations processed concurrently
- Caching: Intelligent caching of frequently accessed data
Webhook Behavior
Real-time Synchronization
- Event Triggering: Webhooks fire for CREATE and UPDATE events only
- Processing Order: Webhooks processed in the order received
- Failure Handling: Failed webhooks automatically retried with backoff
- Duplicate Prevention: Idempotent processing prevents duplicate operations
Webhook Reliability
- Endpoint Availability: Webhook endpoints must be consistently available
- SSL Requirements: HTTPS required for all webhook endpoints
- Authentication: Token-based authentication for webhook security
- Monitoring: Webhook delivery status monitored and logged
Data Mapping Considerations
Field Mapping Behavior
JSONPath Processing
- Path Resolution: Complex nested object paths supported via JSONPath
- Array Handling: First element of arrays used when multiple values exist
- Null Handling: Null or missing values handled gracefully
- Type Conversion: Automatic type conversion between compatible data types
Bidirectional Mapping
- Conflict Resolution: Last modified wins for conflicting updates
- Field Precedence: Neon CRM data takes precedence during pull operations
- WeGive Precedence: WeGive data takes precedence during push operations
- Manual Override: Administrative override available for data conflicts
Custom Field Limitations
- Data Types: Custom fields must have compatible data types
- Field Length: Character limits enforced by Neon CRM field definitions
- Required Fields: Required fields in Neon CRM must be mapped or have defaults
- Option Lists: Neon CRM option lists require exact value matching
Campaign Integration
Campaign Synchronization
- Active Campaigns: Only active campaigns synchronized by default
- Campaign Statistics: Statistics imported from Neon CRM as read-only
- URL Generation: WeGive campaign URLs automatically generated
- Status Mapping: Campaign status properly mapped between platforms
Campaign Limitations
- Historical Data: Historical campaign data may require manual migration
- Complex Hierarchies: Nested campaign structures simplified during sync
- Custom Campaign Fields: Custom campaign fields require explicit mapping
- Event Integration: Event-specific data requires additional configuration
Address Management
Address Synchronization
- Primary Address: Primary address designation preserved
- Multiple Addresses: Only primary address synchronized by default
- Phone Numbers: Phone numbers included with primary address
- Address Types: Mailing and billing addresses handled separately
Address Validation
- Format Requirements: Addresses must meet Neon CRM format requirements
- State/Province: State codes validated against Neon CRM lists
- Country Handling: Country data mapped to Neon CRM country codes
- Zip Code Format: Zip codes validated for proper format
Payment Method Handling
Tender Type Mapping
- Card Processing: Credit card details mapped to Neon offline processing
- Bank Transfers: ACH and bank transfers mapped to check tender type
- Cash Handling: Cash donations properly categorized
- Other Methods: Flexible handling of non-standard payment methods
Payment Security
- PCI Compliance: Sensitive payment data handled per PCI requirements
- Token Storage: Payment tokens securely stored and referenced
- Last Four Digits: Only last four digits of payment methods synchronized
- Expiration Dates: Card expiration dates properly formatted
Error Handling and Recovery
Common Error Scenarios
Authentication Errors
- Invalid Credentials: Clear error messages for invalid API keys
- Permission Errors: Specific errors for insufficient permissions
- Token Expiration: Automatic detection and notification of expired tokens
- Account Suspension: Handling of suspended Neon CRM accounts
Data Validation Errors
- Required Fields: Clear identification of missing required fields
- Format Errors: Specific guidance for data format issues
- Duplicate Data: Intelligent handling of duplicate data scenarios
- Invalid References: Proper handling of invalid foreign key references
Recovery Mechanisms
- Automatic Retry: Failed operations automatically retried with intelligent backoff
- Manual Intervention: Administrative interface for manual error resolution
- Data Correction: Tools for correcting data issues and re-synchronizing
- Rollback Options: Ability to rollback problematic synchronization operations
Integration Limitations
Platform Limitations
Neon CRM Constraints
- API Version: Requires Neon CRM API v2 or higher
- Account Types: Limited to Individual and Company account types
- Custom Fields: Custom field mapping requires manual configuration
- Bulk Operations: Large bulk operations may require batching
WeGive Constraints
- Integration Scope: Limited to core donor management and transaction data
- Real-time Limits: Some operations may have slight delays due to processing
- Custom Logic: Complex business logic may require custom development
- Historical Data: Historical data migration may require special handling
Feature Limitations
- Event Management: Event-specific features require additional configuration
- Volunteer Tracking: Volunteer data not included in standard integration
- Communication History: Email/communication history not synchronized
- File Attachments: Document and file attachments not synchronized
Best Practices for Optimal Performance
Data Quality Management
- Clean Data: Maintain high data quality in both platforms
- Consistent Formats: Use consistent data formats and conventions
- Regular Validation: Periodic validation of synchronized data
- Duplicate Prevention: Proactive duplicate prevention strategies
Monitoring and Maintenance
- Regular Monitoring: Monitor integration performance and error rates
- Log Review: Regular review of integration logs for issues
- Performance Metrics: Track key performance indicators
- Preventive Maintenance: Proactive maintenance to prevent issues
Configuration Management
- Change Control: Implement change control for configuration modifications
- Testing: Thorough testing of configuration changes
- Documentation: Maintain current documentation of configuration settings
- Version Control: Track configuration changes over time
Troubleshooting Common Issues
Sync Failures
- Check Connectivity: Verify network connectivity to both platforms
- Validate Credentials: Confirm API credentials are current and valid
- Review Logs: Examine integration logs for specific error messages
- Test Individual Operations: Isolate issues by testing individual sync operations
Data Inconsistencies
- Compare Records: Compare records between platforms to identify discrepancies
- Review Mappings: Verify field mappings are correct and current
- Check Timestamps: Verify last modified dates to understand sync order
- Manual Correction: Use administrative tools to correct data inconsistencies
Performance Issues
- Monitor API Usage: Check API usage against limits
- Review Batch Sizes: Optimize batch sizes for better performance
- Check Network Latency: Verify network performance between systems
- Optimize Scheduling: Adjust sync schedules to avoid peak usage times
Support and Escalation
Getting Help
- Documentation: Comprehensive documentation and troubleshooting guides
- Support Channels: Multiple support channels for different issue types
- Community Resources: User community and knowledge base
- Professional Services: Advanced implementation and optimization services
Escalation Process
- Level 1: Standard technical support for common issues
- Level 2: Advanced technical support for complex problems
- Level 3: Engineering support for platform-level issues
- Custom Development: Custom development for unique requirements
Understanding these nuances ensures successful implementation and ongoing operation of the WeGive Neon CRM integration. For specific technical details, refer to the Data Mapping Overview documentation.