Overview
Configuration Options
Detailed configuration settings and options for the WeGive Virtuous integration
Configuration Options
The WeGive Virtuous integration provides comprehensive configuration options to control data synchronization behavior, version selection, 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 |
| Version | String | Yes | Integration version (‘v1’ or ‘v2’) - defaults to ‘v1’ |
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
Version Selection
Integration Version
| Setting | Options | Default | Description |
|---|---|---|---|
| Version | ’v1’, ‘v2' | 'v1’ | Choose between legacy V1 or enhanced V2 integration |
Version Selection Impact:
- V1: Simple contact mapping, direct relationships
- V2: Advanced household support, ContactIndividual hierarchy
- Migration: V1 to V2 migration available
- Recommendation: V2 for new implementations
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 |
V1 Push Donors Configuration:
- Creates individual contacts in Virtuous from WeGive donors
- Updates existing contacts when correlation ID exists
- Handles both individual and organization donor types
- Syncs contact information including addresses and communication details
V2 Push Donors Configuration:
- Creates Contact and ContactIndividual hierarchy in Virtuous
- Manages household relationships and primary individuals
- Enhanced organization contact handling
- 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
Version-Specific Configuration
V1 Configuration Options
Contact Management:
- Simple contact mapping rules
- Direct correlation ID management
- Individual and organization contact types
- Standard field mapping configuration
V2 Configuration Options
Enhanced Contact Management:
- Household relationship rules
- Primary individual designation logic
- ContactIndividual management settings
- Enhanced organization handling options
Additional V2 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
- Version Compatibility: Field mapping rules vary between V1 and V2
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
- Use V2 for new implementations
- 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
- Use V2 for enhanced relationship management
- 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
Migration Configuration (V1 to V2 Upgrade)
Purpose: Safely migrate from V1 to V2 integration
Settings:
- Plan household relationship strategy
- Configure primary individual designation rules
- Enable enhanced V2 features gradually
- Maintain data validation during transition
- Monitor migration progress carefully
Best For: Existing V1 customers upgrading to V2 capabilities
Configuration Best Practices
Initial Setup
- Choose Appropriate Version: V2 recommended for new implementations
- 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
- Version Evaluation: Consider V2 upgrade if using V1
- 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: Version-specific problems
- V1: Check simple contact mapping rules
- V2: Verify household relationship configuration
- Migration: Review V1 to V2 transition settings
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
- Version selection is appropriate for needs
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, whether using V1 or V2 architecture.