Salesforce Objects:

• wegive__Communication_List__c (custom object - Lists)
• wegive__Communication_Preference__c (custom object - Preferences/Subscriptions)

WeGive Models:

• CommunicationList
• CommunicationListDonor (pivot/junction table)

​

Overview

This document describes how communication list and preference data syncs between WeGive and Salesforce. These objects work together to manage donor communication preferences and subscriptions:

• Communication Lists - Define the list/segment itself (e.g., “Monthly Newsletter”, “Event Updates”)
• Communication Preferences - Track which donors are subscribed to which lists

Note: These features require the WeGive managed package to be installed in Salesforce, which includes the custom communication objects.

---

​

Part 1: Communication Lists

Salesforce Object: wegive__Communication_List__c
WeGive Model: CommunicationList

​

How Communication List Data Syncs

​

Direction

• Import from Salesforce - Data imports from Salesforce into WeGive only
• Export to Salesforce - Data exports from WeGive to Salesforce only
• Both Ways - Data syncs in both directions

​

Mapping Types

• Hard-coded - Built into the integration logic and cannot be changed

---

​

Sync Triggers - Lists

​

From WeGive to Salesforce (Export)

Communication List data is exported from WeGive to Salesforce when:

• List Created: A new communication list is created in WeGive
• List Updated: An existing list is modified in WeGive (e.g., name changed, description updated, settings modified)

The export happens automatically after the create or update action in WeGive.

​

From Salesforce to WeGive (Import)

Communication List data is imported from Salesforce to WeGive based on:

• Last Modified Date: WeGive periodically polls Salesforce for Communication Lists that have been modified since the last sync
• Sync Frequency: The integration checks for updated Lists on a scheduled basis (frequency varies by integration configuration)
• Modified Field Tracking: Only Lists with a LastModifiedDate newer than the last successful sync are pulled into WeGive

​

Communication List Mappings - Lists

​

Important Notes - Lists

​

List Visibility

Communication lists have multiple visibility settings:

• Visible: Controls whether the list appears in public subscription interfaces
• Show To: Defines which user types can see and subscribe to the list
  • Common values: “all”, “donors”, “admin”
• These settings work together to control list accessibility

​

Double Opt-In

The double_opt_in field controls subscription confirmation:

• When enabled, new subscribers must confirm via email
• Helps ensure GDPR/CAN-SPAM compliance
• Reduces accidental or fraudulent subscriptions
• Recommended for all marketing lists

​

Description Handling

List descriptions can contain HTML in WeGive:

• On export to Salesforce, HTML tags are stripped
• This ensures clean data in Salesforce text fields
• Full HTML description is preserved in WeGive

​

UUID Field

The uuid field provides a stable identifier:

• Used for external integrations (email platforms, etc.)
• Remains consistent even if list is renamed
• Useful for API integrations and webhooks

---

​

Part 2: Communication Preferences (Subscriptions)

Salesforce Object: wegive__Communication_Preference__c
WeGive Model: CommunicationListDonor

​

How Communication Preference Data Syncs

​

Direction

• Import from Salesforce - Data imports from Salesforce into WeGive only
• Export to Salesforce - Data exports from WeGive to Salesforce only
• Both Ways - Data syncs in both directions

​

Mapping Types

• Hard-coded - Built into the integration logic and cannot be changed

---

​

Sync Triggers - Preferences

​

From WeGive to Salesforce (Export)

Communication Preference data is exported from WeGive to Salesforce when:

• Subscription Created: A donor subscribes to a list in WeGive
• Subscription Updated: A subscription status changes (subscribed/unsubscribed)

Prerequisites for Creating Preferences: Before creating a preference in Salesforce, the integration ensures:

1. Donor exists in Salesforce: The donor must have a salesforce_id (Contact) or salesforce_account_id (Account)
2. Communication List exists in Salesforce: The list must have a salesforce_id

The integration will automatically push the donor and list if they don’t have Salesforce IDs yet.

​

From Salesforce to WeGive (Import)

Communication Preference data is imported from Salesforce to WeGive based on:

• Last Modified Date: WeGive periodically polls Salesforce for Communication Preferences that have been modified since the last sync
• Sync Frequency: The integration checks for updated Preferences on a scheduled basis
• Modified Field Tracking: Only Preferences with a LastModifiedDate newer than the last successful sync are pulled into WeGive

---

​

Complete Field Mapping - Preferences

​

Important Notes - Preferences

​

Contact or Account

Communication preferences can link to either:

• Contacts (individual donors) - Uses wegive__Contact__c
• Accounts (company donors) - Uses wegive__Account__c

The integration automatically determines which field to populate based on the donor type. Only one field will be populated per preference record.

​

Subscription Status

The subscribed field tracks the current subscription state:

• true - Donor is currently subscribed to the list
• false - Donor has unsubscribed or never subscribed
• Changes to this field trigger updates in both directions
• This is the primary field for managing list memberships

​

Double Opt-In Tracking

The double_opt_in_required field indicates:

• Whether the subscription required confirmation
• Helps with compliance tracking and auditing
• Set at time of subscription creation
• Typically matches the list’s double opt-in setting

​

Automatic Donor and List Push

When creating a preference, the integration automatically ensures prerequisites:

1. If the donor doesn’t have a Salesforce ID, the donor is pushed first
2. If the list doesn’t have a salesforce_id, the list is pushed first
3. Then the preference relationship is created

This cascading push ensures data integrity without manual intervention.

---

​

Communication List Matching & Create/Update Logic

​

When WeGive Exports a Communication List to Salesforce

Step 1: Check for Existing Salesforce List ID

• If the WeGive list has a salesforce_id: The integration UPDATES the existing List record in Salesforce
• If no salesforce_id exists: The integration CREATES a new List record in Salesforce

​

When Salesforce Exports a Communication List to WeGive

Step 1: Check for Existing WeGive List

• The integration searches for an existing list by salesforce_id
• If found, it updates that list
• If not found, it creates a new list

Step 2: Import Data

• All mapped fields are imported
• Boolean values are properly converted
• Description HTML is preserved in WeGive

---

​

Communication Preference Matching & Create/Update Logic

​

When WeGive Exports a Preference to Salesforce

Step 1: Ensure Prerequisites Exist

• Check if the donor has a Salesforce ID:
  • For individuals: Must have salesforce_id (Contact ID)
  • For companies: Must have salesforce_account_id (Account ID)
  • If not, push the donor first
• Check if the list has a salesforce_id
  • If not, push the list first

Step 2: Check for Existing Salesforce Preference ID

• If the WeGive preference has a salesforce_id: The integration UPDATES the existing Preference record in Salesforce
• If no salesforce_id exists: The integration CREATES a new Preference record in Salesforce

​

When Salesforce Exports a Preference to WeGive

Step 1: Find Related Records

• Find the donor in WeGive:
  • If wegive__Contact__c is set: Search for individual donor with matching salesforce_id
  • If wegive__Account__c is set: Search for company donor with matching salesforce_account_id
  • If donor not found, throw an exception
• Find the list in WeGive by matching wegive__Communication_List__c to salesforce_id
  • If list not found, throw an exception

Step 2: Find or Create Preference The integration searches for an existing preference:

1. First, try to find by salesforce_id
2. If not found, try to find by matching WeGive ID (if wegive__WeGive_ID__c is set)
3. If still not found, try to find by matching donor_id and communication_list_id
4. If still not found, create a new preference

Step 3: Update Preference

• Link to the communication list
• Link to the donor
• Set the subscription status
• Set the double opt-in required flag
• Store the Salesforce ID
• Save the record

​

Why This Matters

This matching logic ensures:

• Each WeGive preference maps to exactly one Salesforce preference record
• The correct donor type (Contact or Account) is used
• Prerequisites (donor and list) always exist before creating the preference
• Subscription status changes are synced in both directions
• No duplicate preferences are created

---

​

Required Fields

For Communication Lists (WeGive to Salesforce):

• Name

For Communication Preferences (WeGive to Salesforce):

• wegive__Contact__c OR wegive__Account__c (Donor reference)
• wegive__Communication_List__c (List Salesforce ID)
• wegive__Subscribed__c (Subscription status)

For Salesforce to WeGive:

• Id (Salesforce ID)
• Communication List and Donor references
• Subscription status

​

Usage in WeGive

Communication Lists and Preferences in WeGive are used for:

• Email Marketing: Segment donors for targeted email campaigns
• Preference Centers: Allow donors to manage their own subscriptions
• Compliance: Track opt-ins and opt-outs for CAN-SPAM/GDPR
• Segmentation: Create donor segments based on interests
• Communication Management: Control who receives what messages
• Double Opt-In: Confirm subscriptions to reduce spam complaints
• Reporting: Analyze subscription trends and list growth

---

​

Usage in Salesforce

Communication Lists and Preferences in Salesforce are used for:

• Marketing Automation: Sync with marketing platforms for email sends
• Preference Tracking: Maintain historical record of subscription changes
• Compliance Reporting: Document opt-in and opt-out activity
• Segmentation: Create Salesforce reports and dashboards by list membership
• Campaign Management: Link lists to Salesforce Campaigns
• Data Integration: Share preference data with other connected systems
• Donor 360: View complete donor communication preferences in one place

---

​

Integration with Contact Fields

In addition to the preference object, WeGive also syncs list subscriptions as custom fields on the Contact record. This provides an alternative view of subscription data:

• Each communication list can have a corresponding custom field on Contact
• Field API name follows pattern: CL_[list_id]_[list_slug]
• Field stores boolean true/false for subscribed/unsubscribed
• This allows for easier reporting and filtering in Salesforce
• Both the preference records and Contact fields are maintained

Example:

• List ID: 123
• List Slug: monthly_newsletter
• Contact Field: CL_123_monthly_newsletter
• Value: true (if subscribed) or false (if unsubscribed)

---

​

Best Practices

1. Use double opt-in for all marketing lists to ensure compliance
2. Create clear list names that describe the content type
3. Write descriptive list descriptions so donors know what they’re subscribing to
4. Set appropriate visibility - not all lists need to be publicly visible
5. Respect unsubscribe requests - sync them immediately
6. Audit preferences regularly to ensure data accuracy
7. Document list purposes for internal team reference
8. Test subscription flows before launching new lists
9. Monitor sync logs for failed preference updates
10. Coordinate with marketing team on list strategy and usage

---

​

Troubleshooting

Communication list not syncing:

• Verify the WeGive managed package is installed
• Check that list has been modified since last sync
• Ensure integration has access to wegive__Communication_List__c object

Preference not syncing:

• Verify donor has a Salesforce ID (Contact or Account)
• Check that list has a salesforce_id
• Ensure integration has access to wegive__Communication_Preference__c object
• Verify donor type matches expected object (Contact vs Account)

Subscription status not updating:

• Check that the subscribed field is being updated in both systems
• Verify sync is running and processing preference changes
• Ensure no competing processes are overwriting status

Duplicate preferences:

• Preferences should be unique per donor + list combination
• If duplicates exist, they may have been created outside the integration
• Delete duplicates in Salesforce, keeping the one with correct status

Company donors not subscribing:

• Verify company donors have salesforce_account_id populated
• Ensure wegive__Account__c field is being used (not wegive__Contact__c)
• Check that Account record exists in Salesforce

Double opt-in not working:

• Verify the double_opt_in setting on the list
• Check that email confirmation workflows are configured
• Ensure the double_opt_in_required field is being set correctly

Contact custom fields not syncing:

• These are handled separately from preference objects
• Check that custom field mapping rules exist for the Contact
• Verify field API names follow the CL_[id]_[slug] pattern

---

​

Understanding Hard-coded Mappings

All communication list and preference field mappings are hard-coded because:

• The WeGive managed package defines the object structure
• The data model is standardized across all implementations
• Custom fields are rarely needed on these objects
• The integration needs to handle both Contact and Account preferences automatically

---

​

Compliance Considerations

Communication preferences are critical for compliance with:

• CAN-SPAM Act: Track opt-outs and honor unsubscribe requests
• GDPR: Maintain consent records and allow preference management
• CASL (Canada): Document consent and manage subscriptions
• State Privacy Laws: Provide transparency and control over communications

The integration helps maintain compliance by:

• Syncing subscription status immediately
• Tracking double opt-in confirmations
• Preserving historical preference data
• Enabling self-service preference management