Integration Nuances
This document outlines important behaviors, limitations, and considerations when using the WeGive Bloomerang integration.Data Flow Overview
The WeGive Bloomerang integration provides seamless bidirectional synchronization between your platforms using:- Bloomerang API v2: Industry-standard RESTful API
- Real-time Sync: Immediate updates for critical data changes
- Batch Processing: Efficient handling of large data sets
- Rate Limiting: Respectful API usage (1000 requests per hour)
Sync Timing and Frequency
Automatic Synchronization
Real-time Events:- New donations are immediately sent to Bloomerang
- Donor profile updates sync within minutes
- Fund changes propagate automatically
- Bulk data imports run on configurable schedules
- Historical data sync occurs during off-peak hours
- Error recovery processes run automatically
Data Handling
What Gets Synchronized
From WeGive to Bloomerang:- New donor profiles (individuals and organizations)
- Donation transactions with payment details
- Fund and designation information
- Contact information updates
- Existing constituent records
- Historical donation data
- Fund structures and categories
- Updated contact information
Data Matching and Deduplication
Smart Matching Logic:- Email addresses for individual donors
- Organization names for corporate donors
- Prevents duplicate record creation
- Maintains data integrity across platforms
- Most recent update takes precedence
- Manual review flagging for complex conflicts
- Automatic retry for temporary sync issues
Important Behaviors
Name Handling
Individual Donors:- If first name is missing, defaults to “FNU” (First Name Unknown)
- If last name is missing, defaults to “LNU” (Last Name Unknown)
- This ensures all records meet Bloomerang requirements
- Full organization name is required
- Duplicate organization names are handled automatically
Payment Method Mapping
Supported Payment Types:- Credit/debit cards → CreditCard in Bloomerang
- Bank transfers/ACH → EFT in Bloomerang
- Checks → Check in Bloomerang
- Cash donations → Cash in Bloomerang
- Other methods → None in Bloomerang
Fund Designations
Default Fund Behavior:- All transactions must have a fund designation
- If no fund is specified, uses your configured default fund
- Multiple fund allocations are supported for split gifts
Address Synchronization
Address Formatting:- Street address lines are combined in Bloomerang
- Country defaults to “United States” if not specified
- International addresses are supported
Limitations and Considerations
API Rate Limits
Bloomerang Limits:- 1000 API requests per hour
- Automatic retry with exponential backoff
- Large syncs may take longer due to rate limiting
Data Volume Considerations
Initial Sync:- Large datasets (10,000+ records) may take several hours
- Sync occurs in background without affecting daily operations
- Progress tracking available in integration logs
- Real-time for individual transactions
- Batch processing for bulk updates
- Minimal impact on system performance
Data Requirements
Required Fields:- Donors must have either first name or last name (individuals)
- Organizations must have a name
- Transactions must have an amount and date
- At least one fund must exist for transaction mapping
Sync Direction Considerations
Bidirectional Sync Caution:- Carefully consider which direction to enable for each data type
- Bidirectional sync can lead to data ping-ponging if not configured properly
- Test thoroughly before enabling full bidirectional sync
- Start with WeGive → Bloomerang push only
- Add pull operations after validating data quality
- Enable bidirectional sync only when necessary
Error Handling
Common Sync Issues
Authentication Errors:- Invalid API key - regenerate in Bloomerang settings
- Expired credentials - rotate API keys regularly
- Missing required fields - check data completeness
- Invalid email formats - clean email data before sync
- Duplicate records - review matching criteria
- Connection timeouts - automatic retry handles most cases
- Service unavailable - sync resumes when service is restored
Automatic Recovery
Built-in Resilience:- Failed records are queued for retry
- Exponential backoff prevents API overload
- Manual retry options available in dashboard
Error Notifications
Alert Types:- Critical errors appear in dashboard immediately
- Email notifications for sustained failures
- Weekly summary reports for integration health
Best Practices
Data Quality
Before Integration:- Clean duplicate records in both systems
- Standardize naming conventions
- Validate email addresses and phone numbers
- Ensure consistent fund structures
- Monitor integration logs weekly
- Review and resolve sync conflicts promptly
- Maintain clean data in both systems
- Regular backup of critical data
Performance Optimization
Sync Configuration:- Enable only necessary sync directions
- Use scheduled sync for large historical imports
- Monitor API usage to stay within limits
- Configure appropriate batch sizes
Security Considerations
API Key Management:- Store API keys securely
- Rotate keys quarterly
- Monitor for unexpected API usage
- Restrict access to integration settings
- Ensure compliance with data protection regulations
- Understand data residency requirements
- Review data sharing agreements
- Maintain audit trails
Troubleshooting Tips
Sync Performance
Slow Initial Sync:- Normal for large datasets
- Monitor progress in integration logs
- Consider syncing in smaller batches
- Sync during off-peak hours
- Check network connectivity
- Verify API key is valid
- Review rate limiting status
- Check Bloomerang service status
Data Accuracy
Missing Records:- Verify sync direction settings
- Check data meets requirements
- Review matching criteria
- Look for validation errors in logs
- Review matching logic
- Check for email address conflicts
- Verify organization name uniqueness
- Consider manual deduplication
Integration Monitoring
Regular Health Checks:- Test connection monthly
- Review error rates and trends
- Monitor sync success percentages
- Validate data accuracy periodically