Configuration Options
Configuration Options
The WeGive Virtuous integration provides comprehensive configuration options to control data synchronization behavior, sync frequency, and integration features.
Authentication Settings
API Configuration
| Setting | Type | Required | Description |
|---|---|---|---|
| API Key | String | Yes | Your Virtuous API key for authentication |
| Enabled | Boolean | Yes | Master toggle to enable/disable the entire integration |
API Key Configuration
- Source: Generated from Virtuous Settings → API Keys
- Security: Encrypted and stored securely in WeGive
- Validation: Automatically tested during configuration
- Rotation: Should be rotated periodically for security
Synchronization Controls
Data Type Configuration
Configure what types of data synchronize between platforms:
Donors/Contacts Sync
| Setting | Default | Description |
|---|---|---|
| Push Donors | Enabled | Send WeGive donors to Virtuous as contacts |
| Pull Donors | Disabled | Import Virtuous contacts to WeGive as donors |
Push Donors Configuration:
- Creates Contact and ContactIndividual hierarchy in Virtuous
- Manages household relationships and primary individuals
- Handles organization contact records
- Maintains family and relationship structures
Transactions/Gifts Sync
| Setting | Default | Description |
|---|---|---|
| Push Transactions | Enabled | Send WeGive donations to Virtuous as gifts |
| Pull Transactions | Disabled | Import Virtuous gifts to WeGive |
Push Transactions Configuration:
- Sends successful WeGive donations to Virtuous
- Maps payment methods and gift types
- Links gifts to appropriate contacts and projects
- Includes transaction metadata and processing details
- Supports batch processing for efficiency
Funds/Projects Sync
| Setting | Default | Description |
|---|---|---|
| Push Funds | Enabled | Send WeGive funds to Virtuous as projects |
| Pull Funds | Disabled | Import Virtuous projects to WeGive |
Campaigns/Segments Sync
| Setting | Default | Description |
|---|---|---|
| Push Campaigns | Enabled | Send WeGive campaigns to Virtuous as segments |
| Pull Campaigns | Disabled | Import Virtuous segments to WeGive |
Recurring Donations Sync
| Setting | Default | Description |
|---|---|---|
| Push Scheduled Donations | Enabled | Send WeGive recurring plans to Virtuous |
| Pull Scheduled Donations | Disabled | Import Virtuous recurring gifts to WeGive |
Advanced Settings
Required Configuration
| Setting | Type | Required | Description |
|---|---|---|---|
| Default Project ID | String | Yes | Virtuous project ID for gifts without specific designation |
| Default Communication ID | String | Yes | Virtuous communication ID for creating segments |
Important Notes:
- Default Project ID: Must be a valid, active project ID from your Virtuous account
- Default Communication ID: Required for campaign/segment creation functionality
- Used when WeGive transactions or campaigns don’t have specific mappings
Sync Behavior Settings
| Setting | Options | Default | Description |
|---|---|---|---|
| Real Time | Enabled/Disabled | Disabled | Enable real-time sync via webhooks |
| Pull By | Field options | ’Last Modified Date’ | Field to use for pulling data from Virtuous |
Real-time Sync:
- Immediate synchronization for critical updates
- Utilizes Virtuous webhooks for instant notifications
- Best for organizations requiring immediate data consistency
- Requires webhook configuration in Virtuous
Scheduled Sync:
- Daily batch processing for bulk operations
- More efficient for large data volumes
- Reduces API usage and rate limit concerns
- Default sync method for most organizations
Data Flow Configuration
Sync Direction Matrix
| Data Type | Push (WeGive → Virtuous) | Pull (Virtuous → WeGive) | Bidirectional |
|---|---|---|---|
| Donors/Contacts | Configurable | Configurable | Supported |
| Transactions/Gifts | Configurable | Configurable | Supported |
| Funds/Projects | Configurable | Configurable | Supported |
| Campaigns/Segments | Configurable | Configurable | Supported |
| Recurring Donations | Configurable | Configurable | Supported |
Conflict Resolution
When the same record exists in both systems:
For Push Operations (WeGive → Virtuous):
- WeGive data takes precedence
- Virtuous records are updated with WeGive values
- Correlation IDs prevent duplicate creation
For Pull Operations (Virtuous → WeGive):
- Virtuous data takes precedence
- WeGive records are updated with Virtuous values
- Existing relationships are preserved
Contact Configuration
Contact Management:
- Household relationship rules
- Primary individual designation logic
- ContactIndividual management settings
- Organization handling options
Additional Settings:
- Contact hierarchy management
- Family relationship coordination
- Primary contact individual rules
- Household address coordination
Integration Features
Data Processing Options
| Setting | Options | Default | Description |
|---|---|---|---|
| Batch Processing | Enabled/Disabled | Enabled | Process transactions in batches for efficiency |
| Error Handling | Standard/Enhanced | Standard | Level of error handling and retry logic |
| Data Validation | Basic/Comprehensive | Basic | Extent of data validation before sync |
Monitoring and Logging
| Setting | Options | Default | Description |
|---|---|---|---|
| Log Level | Minimal/Standard/Detailed | Standard | Amount of detail in integration logs |
| Performance Tracking | Enabled/Disabled | Enabled | Track sync performance and timing |
| Error Notifications | Dashboard/Email/Both | Dashboard | How to receive error notifications |
Organization-Specific Settings
Custom Field Mapping
Organizations can configure custom field mappings between WeGive and Virtuous:
- Field Pairing: Map specific WeGive fields to corresponding Virtuous fields
- Data Type Matching: Ensure compatible data types between systems
- Validation Rules: Custom fields follow the same validation as standard fields
Data Filters
| Filter Type | Description | Example |
|---|---|---|
| Date Range | Limit sync to specific date ranges | Last 12 months |
| Amount Threshold | Only sync transactions above certain amount | $25 minimum |
| Contact Type | Filter by individual vs organization | Individual only |
| Project Categories | Restrict which projects synchronize | Operating funds only |
API Configuration
Rate Limiting
| Setting | Behavior | Description |
|---|---|---|
| API Requests | Virtuous limits | Respects Virtuous API rate limiting |
| Batch Optimization | Automatic | Uses batch endpoints when available |
| Retry Logic | Built-in | Automatic retry with exponential backoff |
Performance Settings
| Setting | Default | Range | Description |
|---|---|---|---|
| Batch Size | 100 | 25-500 | Records processed per batch operation |
| Concurrent Operations | 3 | 1-5 | Number of simultaneous API operations |
| Timeout Settings | 30 seconds | 10-60 seconds | API request timeout duration |
Recommended Configuration Approaches
Standard Configuration (Most Organizations)
Purpose: Send WeGive data to Virtuous while maintaining Virtuous as the authoritative source
Settings:
- Enable push for donors, transactions, funds, and campaigns
- Disable pull operations initially
- Enable batch processing for efficiency
- Configure real-time sync for critical updates
Best For: Organizations that want to enrich their Virtuous data with WeGive activity
Bidirectional Configuration (Advanced Users)
Purpose: Keep both systems completely synchronized
Settings:
- Enable both push and pull for all data types
- Enable real-time sync for immediate updates
- Configure comprehensive error handling
- Monitor performance closely
Best For: Organizations that actively use both platforms and need complete data synchronization
Configuration Best Practices
Initial Setup
- Test Thoroughly: Use test connection before enabling sync
- Start Conservative: Begin with push-only configuration
- Monitor Closely: Watch logs during first 24-48 hours
- Validate Data: Verify accuracy of synced records
Ongoing Management
- Regular Reviews: Check configuration monthly
- Performance Monitoring: Track sync times and success rates
- Error Analysis: Review and resolve integration errors promptly
- Settings Optimization: Adjust configuration based on usage patterns
Security Considerations
- API Key Rotation: Update API keys quarterly
- Access Control: Limit who can modify integration settings
- Audit Logging: Maintain records of configuration changes
- Data Privacy: Ensure compliance with data protection regulations
Troubleshooting Configuration Issues
Common Problems
Issue: Sync operations failing
- Check: Verify all required settings are configured
- Verify: Test API connection is successful
- Review: Ensure default project and communication IDs are valid
Issue: Duplicate records being created
- Check: Correlation ID mapping is working correctly
- Verify: Email matching is functioning properly
- Review: Sync direction settings are appropriate
Issue: Contact relationship problems
- Check: Verify household relationship configuration
- Verify: Primary contact individual designation is consistent
Issue: Performance problems
- Check: Batch size settings are optimal
- Verify: Rate limiting is not being exceeded
- Review: Real-time vs batch sync configuration
Configuration Validation
Required Fields Check:
- API key is valid and has proper permissions
- Default project ID exists and is active
- Default communication ID is valid
Data Quality Verification:
- Field mappings are configured correctly
- Custom field rules are properly defined
- Filter settings match organizational needs
- Error handling is appropriately configured
This comprehensive configuration guide ensures optimal setup and ongoing management of your WeGive Virtuous integration.