Technical Implementation Guide

Technical Implementation Guide

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

Integration Architecture

Our Salesforce integration is built on a layered 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

The main integration class (App\Integrations\Salesforce) provides:

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

The SalesforceIntegration model (App\Models\SalesforceIntegration) handles:

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

Field mapping is managed through the SalesforceIntegration model:

// 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

The integration implements comprehensive 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