Overview
Integration Nuances
Important considerations and behaviors of the WeGive Planning Center integration
Integration Nuances
This document outlines important behaviors, limitations, and considerations when using the WeGive Planning Center integration, including specific features of the People and Giving modules.
Authentication Behaviors
OAuth 2.0 Flow
Authentication Process:
- Initial OAuth authorization redirects to Planning Center
- User grants permission for ‘people giving’ scopes
- Authorization code exchanged for access and refresh tokens
- Automatic token refresh without user intervention
Token Management:
- Access tokens automatically refreshed before expiration
- Refresh tokens stored securely for ongoing authentication
- Failed token refresh triggers re-authorization flow
- Token scope limited to People and Giving modules only
Legacy Authentication
Basic Auth Process:
- Uses Application ID and Personal Access Token
- Direct API authentication without OAuth flow
- Manual token rotation required for security
- Same scope access as OAuth (people and giving)
Migration Considerations:
- OAuth 2.0 recommended for new implementations
- Legacy auth continues to work for existing setups
- Migration to OAuth available without data loss
Data Flow Behaviors
Daily Batch Processing
WeGive Import Batches:
- Daily batches created automatically at 8:01 AM
- Batch name format: “WeGive Import - [Date]”
- All WeGive transactions for the day included in single batch
- Automatic batch commitment after successful processing
Batch Processing Logic:
- Transactions grouped by donation date, not processing date
- Missing transaction batches detected and created automatically
- Failed batch processing triggers rollback of entire batch
- Batch status tracked for audit and troubleshooting
Fund Assignment Logic
Priority Order for Fund Assignment:
- Specific Fund: Use designated fund from WeGive transaction
- Default Fund: Fall back to configured default fund
- Fund Creation: Create new fund if specified fund doesn’t exist
- General Fund: Use organization’s general fund as final fallback
Fund Visibility Handling:
- Hidden funds in Planning Center marked as deleted in WeGive
- Fund visibility changes sync bidirectionally
- Fund creation requires active status in Planning Center
- Fund deletion preserves historical transaction references
Contact Management Behaviors
Person Record Matching
Matching Strategy (in order of preference):
- Planning Center ID: Exact match using stored correlation ID
- Email Address: Primary email address matching
- Name Matching: Full name comparison for individuals
- Create New: When no match found
Contact Information Handling:
- Primary email address mapped to main email field
- Additional email addresses stored as secondary contacts
- Phone numbers categorized by type (mobile, home, work)
- Address information synchronized with full geographic data
Family and Household Relationships
Family Coordination:
- Individual person records maintained separately
- Family relationships preserved in Planning Center structure
- Household addresses coordinated across family members
- Contact preferences managed at individual level
Payment Source Management
WeGive Payment Source
Single Payment Source Strategy:
- All WeGive transactions use “WeGive” payment source in Planning Center
- Payment method details preserved in transaction metadata
- Simplifies Planning Center payment source management
- Enables unified reporting across all WeGive payment types
Payment Method Mapping:
- Credit cards, ACH, checks all attributed to “WeGive” source
- Original payment method preserved in transaction details
- Payment source creation automatic during initial setup
- Payment source reused for all subsequent transactions
API Rate Limiting and Performance
Planning Center API Limits
Rate Limiting Rules:
- 70 requests per 20-second window
- Automatic rate limit detection and compliance
- Request queuing during rate limit periods
- Intelligent batching to optimize API usage
Performance Optimization:
- Incremental sync for efficiency (only changed data)
- Batch operations for bulk data processing
- Request optimization to minimize API calls
- Background job processing for time-intensive operations
Large Data Set Handling
Initial Sync Considerations:
- Large datasets may require extended processing time
- Progress tracking available for long-running sync operations
- Checkpoint system for resuming interrupted syncs
- Memory optimization for processing large volumes
Error Handling and Recovery
Automatic Error Recovery
Retry Logic:
- Failed API requests automatically retried up to 3 times
- Exponential backoff prevents API overload
- Different retry strategies for different error types
- Manual retry options available for persistent failures
Batch Error Handling:
- Single transaction failure doesn’t fail entire batch
- Failed transactions quarantined for manual review
- Batch rollback capability for critical errors
- Comprehensive error logging for troubleshooting
Common Error Scenarios
Authentication Errors:
- Token expiration handled automatically with refresh
- Scope permission errors logged with clear messages
- Invalid credentials trigger re-authentication flow
- Network connectivity issues handled with retries
Data Validation Errors:
- Missing required fields cause transaction rejection
- Invalid fund IDs trigger default fund assignment
- Duplicate detection prevents record conflicts
- Data format errors logged with specific field information
Sync Timing and Scheduling
Daily Processing Schedule
Automated Operations:
- 8:01 AM: Daily batch generation for previous day’s transactions
- 8:15 AM: Pull sync for updated Planning Center data
- Continuous: Real-time processing for immediate updates (when enabled)
- Weekly: Comprehensive data validation and cleanup
Manual Sync Options:
- Full sync available for complete data refresh
- Incremental sync for recent changes only
- Specific date range sync for historical data
- Test sync for configuration validation
Incremental vs. Full Sync
Incremental Sync Benefits:
- Faster processing for daily operations
- Lower API usage and better performance
- Focuses on recently changed data only
- Maintains sync efficiency for ongoing operations
Full Sync Use Cases:
- Initial integration setup
- Data quality audits and cleanup
- Recovery from extended outages
- Configuration changes requiring complete refresh
Fund and Designation Behaviors
Fund Creation and Management
Automatic Fund Creation:
- Missing funds created automatically when referenced
- Fund names synchronized between systems
- Fund descriptions and metadata preserved
- Fund status (active/inactive) coordinated
Fund Designation Logic:
- Split designations supported for multiple funds
- Designation amounts validated against transaction total
- Fund allocation percentages calculated automatically
- Undesignated amounts assigned to default fund
Recurring Gift Coordination
Recurring Gift Processing:
- Planning Center recurring gifts linked to WeGive scheduled donations
- Recurring gift schedules synchronized bidirectionally
- Individual gifts created from recurring gift schedules
- Schedule modifications reflected in both systems
Data Quality and Validation
Contact Information Validation
Email Validation:
- Email format validation before sync
- Duplicate email detection within organization
- Invalid emails logged but don’t prevent contact creation
- Email preference coordination between systems
Address Standardization:
- Address formatting normalized for consistency
- Geographic data validation where possible
- International address support with country codes
- Address type designation (home, work, mailing)
Financial Data Validation
Transaction Validation:
- Amount validation ensures positive values
- Date validation prevents future-dated transactions
- Fund validation confirms fund exists and is active
- Currency validation for international organizations
Reporting and Analytics Integration
Financial Reporting Coordination
Batch Reporting:
- Daily batch summaries for accounting reconciliation
- Transaction counts and totals for validation
- Fund allocation reports for designation tracking
- Error reports for data quality monitoring
Donor Analytics:
- Giving history synchronized between systems
- Donor engagement metrics coordinated
- Contact communication history preserved
- Giving pattern analysis supported
Security and Compliance
Data Privacy Considerations
Information Sharing:
- Only necessary data synchronized between systems
- Contact preferences respected in both platforms
- Data retention policies coordinated
- Privacy compliance maintained across integration
Access Control:
- Integration access limited to configured scopes
- API permissions validated during setup
- Audit logs maintained for all sync operations
- Security monitoring for unusual activity patterns
Performance Monitoring
Integration Health Checks
Automated Monitoring:
- Daily batch processing success rates
- API response times and error rates
- Data sync completion status
- Integration performance metrics
Alert Conditions:
- Failed batch processing
- Extended API response times
- High error rates in data sync
- Authentication or permission failures
Best Practices for Optimal Performance
Data Management
Regular Maintenance:
- Weekly review of integration logs
- Monthly data quality audits
- Quarterly configuration reviews
- Annual authentication credential rotation
Optimization Strategies:
- Monitor API usage patterns
- Optimize sync scheduling for off-peak hours
- Regular cleanup of unused or duplicate data
- Performance tuning based on usage patterns
Troubleshooting Preparation
Diagnostic Information:
- Maintain current integration logs
- Document configuration changes
- Keep backup of critical data
- Monitor system performance trends
This understanding of integration nuances will help you successfully implement and maintain the WeGive Planning Center integration while avoiding common pitfalls and ensuring optimal performance for your church management needs.