> ## Documentation Index
> Fetch the complete documentation index at: https://wegive.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Data Models & Integration

> Detailed documentation of our Salesforce NPSP data models and integration patterns

# Data Models & Integration

Our Salesforce NPSP integration is built on a comprehensive data model that maps our donor experience platform to Salesforce objects. This document outlines the key objects and their relationships.

## Core Objects

### Donors & Households

* **Contact (Donor)**
  * Maps to our `Donor` model
  * Handles individual donor information
  * Supports both individual and organizational donors
  * Includes merge functionality for duplicate contacts

* **Account (Household)**
  * Maps to our `Household` model
  * Manages household and organizational relationships
  * Supports the NPSP Household Account Model
  * Handles both individual and company accounts

### Donations & Transactions

* **Opportunity**
  * Maps to our `Transaction` model
  * Represents individual donations
  * Includes payment information
  * Supports allocation to multiple funds

* **npe01\_\_OppPayment\_\_c**
  * Stores payment details for transactions
  * Maps payment methods and statuses
  * Handles payment processing information

* **npe03\_\_Recurring\_Donation\_\_c**
  * Maps to our `ScheduledDonation` model
  * Manages recurring gift schedules
  * Tracks payment frequency and status

* **npe4\_\_Pledge\_\_c**
  * Maps to our `Pledge` model
  * Handles pledge commitments
  * Tracks pledge status and fulfillment

### Campaigns & Engagement

* **Campaign**
  * Maps to our `Campaign` model
  * Manages fundraising campaigns
  * Tracks campaign members and donors
  * Supports campaign events and fundraisers

* **CampaignMember**
  * Maps to our `CampaignDonor` model
  * Tracks donor participation in campaigns
  * Manages campaign engagement

* **npe01\_\_OppPayment\_\_c**
  * Handles soft credits
  * Tracks influence and attribution
  * Supports both account and partial soft credits

### Additional Features

* **Communication Lists**
  * Maps to our `CommunicationList` model
  * Manages donor communication preferences
  * Tracks communication list memberships

* **Campaign Events**
  * Supports event management
  * Handles event registrations
  * Manages event tickets
  * Tracks fundraiser campaigns

## Field Mappings

Our integration supports extensive field mapping through the `SalesforceIntegration` model, which provides field options for:

* Contact fields
* Account fields
* Opportunity fields
* Campaign fields
* Payment fields
* Recurring Donation fields
* Pledge fields
* GAU (General Accounting Unit) fields
* Campaign Event fields
* Communication List fields
* Soft Credit fields

## Integration Patterns

### Data Synchronization

Our integration implements several key synchronization patterns:

1. **Pull Operations**
   * `pullDonors()`: Synchronizes donor data
   * `pullCampaigns()`: Updates campaign information
   * `pullTransactions()`: Retrieves donation data
   * `pullSoftCredits()`: Syncs soft credit information
   * `pullScheduledDonations()`: Updates recurring gifts
   * `pullPledges()`: Syncs pledge information

2. **Push Operations**
   * `pushDonor()`: Updates donor information
   * `pushTransaction()`: Creates/updates donations
   * `pushCampaign()`: Manages campaign data
   * `pushSoftCredit()`: Updates soft credits
   * `pushPledge()`: Manages pledge data

3. **Special Operations**
   * Merge handling for contacts and accounts
   * Deletion tracking for various objects
   * Fund allocation management
   * Campaign member synchronization

## Best Practices

When working with our Salesforce integration:

1. **Data Synchronization**
   * Use the provided pull/push methods for data operations
   * Respect the synchronization patterns
   * Handle merge operations through the dedicated methods

2. **Field Mapping**
   * Use the field options attributes for mapping
   * Follow the established field naming conventions
   * Maintain mapping consistency across objects

3. **Error Handling**
   * Monitor integration logs
   * Handle API rate limits appropriately
   * Implement proper error recovery

4. **Performance**
   * Use batch operations when possible
   * Implement proper indexing
   * Monitor API call limits

## API Integration

Our integration uses a custom HTTP client for Salesforce API communication:

* OAuth 2.0 authentication
* Token management and refresh
* Rate limiting handling
* Batch operation support

## Monitoring & Logging

The integration includes comprehensive logging through:

* Integration logs
* API call tracking
* Error monitoring
* Performance metrics