Technical Implementation Guide

This guide provides technical details about our Salesforce NPSP integration implementation.

Integration Architecture

1. Base Integration Layer
   • CrmIntegration base class
   • Common CRM operations
   • Authentication handling
2. Salesforce Specific Layer
   • Salesforce class extending CrmIntegration
   • NPSP-specific implementations
   • Custom Salesforce API handling
3. Model Layer
   • SalesforceIntegration model
   • Field mapping management
   • Integration configuration

Core Classes

Salesforce Integration Class

class Salesforce extends CrmIntegration
{
    // Authentication and connection management
    protected function accessToken()
    protected function http()
    
    // Data synchronization methods
    public function pullDonors()
    public function pullCampaigns()
    public function pullTransactions()
    // ... other pull methods
    
    public function pushDonor()
    public function pushTransaction()
    public function pushCampaign()
    // ... other push methods
}

Salesforce Integration Model

class SalesforceIntegration extends Model
{
    // Field mapping management
    public function getContactFieldOptionsAttribute()
    public function getAccountFieldOptionsAttribute()
    public function getOpportunityFieldOptionsAttribute()
    // ... other field options
    
    // Integration configuration
    public function setupDefaultMappings()
    public function createMappingRule()
}

Key Implementation Patterns

1. Data Synchronization

Pull Operations

// Example pull operation
protected function pullDonors($from = null, $to = null)
{
    // SOQL query construction
    // Data transformation
    // Model creation/update
}

// Example push operation
public function pushTransaction(Transaction $transaction)
{
    // Payload compilation
    // API call
    // Response handling
}

2. Field Mapping

// Example field options
public function getContactFieldOptionsAttribute()
{
    return $this->getFieldOptions('Contact');
}

// Mapping rule creation
public function createMappingRule($data)
{
    // Rule validation
    // Mapping creation
    // Configuration update
}

3. Data Transformation

Payload Compilation

// Example payload compilation
public function compileDonorPayload(Donor $donor): array
{
    // Field mapping
    // Data transformation
    // Validation
}

public function compileTransactionPayload(Transaction $transaction)
{
    // Opportunity creation
    // Payment handling
    // Allocation management
}

4. Error Handling

// Example error handling
protected function handleApiError($response)
{
    // Error logging
    // Rate limit handling
    // Retry logic
}

API Integration Details

Authentication

protected function accessToken()
{
    // OAuth token management
    // Token refresh
    // Error handling
}

HTTP Client

public function http()
{
    // Client configuration
    // Headers management
    // Rate limiting
}

Data Models

Core Models

1. Donor Model
   • Maps to Salesforce Contact
   • Handles individual and organizational donors
   • Supports merge operations
2. Transaction Model
   • Maps to Salesforce Opportunity
   • Includes payment information
   • Supports allocations
3. Campaign Model
   • Maps to Salesforce Campaign
   • Manages campaign members
   • Supports events and fundraisers

Supporting Models

1. ScheduledDonation
   • Maps to Recurring Donation
   • Payment schedule management
2. Pledge
   • Maps to NPSP Pledge
   • Commitment tracking
3. SoftCredit
   • Influence tracking
   • Attribution management

Best Practices

1. API Usage

• Implement proper rate limiting
• Use batch operations when possible
• Handle API errors gracefully
• Monitor API call limits

2. Data Management

• Use provided sync methods
• Follow field mapping conventions
• Implement proper validation
• Handle merges correctly

3. Performance

• Implement caching where appropriate
• Use batch operations
• Monitor API call patterns
• Optimize query patterns

4. Security

• Secure token management
• Proper error handling
• Data validation
• Access control

Troubleshooting

Common Issues

1. API Rate Limits
   • Monitor API call patterns
   • Implement proper retry logic
   • Use batch operations
2. Data Synchronization
   • Check field mappings
   • Verify data transformation
   • Monitor sync logs
3. Authentication
   • Token refresh handling
   • Connection management
   • Error recovery

Debugging

1. Logging
   • Integration logs
   • API call tracking
   • Error monitoring
2. Monitoring
   • Performance metrics
   • API usage
   • Sync status

Development Guidelines

1. Code Structure
   • Follow existing patterns
   • Maintain separation of concerns
   • Document new features
2. Testing
   • Unit test new features
   • Integration testing
   • API mocking
3. Documentation
   • Update field mappings
   • Document new features
   • Maintain technical docs