Overview
Integration Nuances
Important considerations and behaviors of the WeGive Bloomerang integration
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
Scheduled Operations:
- 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
From Bloomerang to WeGive:
- 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
Conflict Resolution:
- 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
Organization Donors:
- 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
Ongoing Sync:
- 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
Recommended Approach:
- 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
Data Validation Errors:
- Missing required fields - check data completeness
- Invalid email formats - clean email data before sync
- Duplicate records - review matching criteria
Network Issues:
- 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
Ongoing Maintenance:
- 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
Data Privacy:
- 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
Real-time Sync Delays:
- 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
Duplicate Records:
- 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
This understanding of integration nuances will help you successfully implement and maintain the WeGive Bloomerang integration while avoiding common pitfalls and ensuring optimal performance.