​

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

​

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

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

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

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

​

Campaigns/Segments Sync

​

Recurring Donations Sync

​

Advanced Settings

​

Required Configuration

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

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

​

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

​

Monitoring and Logging

​

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

​

API Configuration

​

Rate Limiting

​

Performance Settings

​

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

1. Choose Appropriate Version: V2 recommended for new implementations
2. Test Thoroughly: Use test connection before enabling sync
3. Start Conservative: Begin with push-only configuration
4. Monitor Closely: Watch logs during first 24-48 hours
5. Validate Data: Verify accuracy of synced records

​

Ongoing Management

1. Regular Reviews: Check configuration monthly
2. Performance Monitoring: Track sync times and success rates
3. Error Analysis: Review and resolve integration errors promptly
4. Version Evaluation: Consider V2 upgrade if using V1
5. Settings Optimization: Adjust configuration based on usage patterns

​

Security Considerations

1. API Key Rotation: Update API keys quarterly
2. Access Control: Limit who can modify integration settings
3. Audit Logging: Maintain records of configuration changes
4. 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.