Overview#

Flow name: MoveData_Donation_Donation_Mapping Label: [MoveData] Donation: Donation - Mapping Type: Auto-Launched Flow Template API version: 60.0 Status: Active

This flow handles the comprehensive mapping and transformation of donation data from external platforms into Salesforce NPSP-enabled Opportunity records. It processes donations across multiple statuses including successful payments, refunds, failures, pledges, and matching gift scenarios.

Purpose#

The flow processes incoming donation data and maps it to appropriate Salesforce NPSP fields while handling:

• Multi-status donation processing (success, refund, failed, pledge, offline, static)
• Donor relationship management (Contact/Account assignment including anonymous donations)
• Currency setting and fee calculations with platform fee deduction options
• Recurring donation parent-child relationships
• Matching gift processing and employer attribution
• NPSP Payment record creation for refunds
• Date conversions and close date management
• Fee tracking across multiple fee types (platform, gateway, taxes)
• Dynamic donation naming with configurable patterns

Salesforce fields#

The flow interacts with multiple Salesforce objects and their fields. Below is a comprehensive mapping of all fields utilised:

Input variables#

Core donation data#

Related records#

Platform integration#

Fee structure#

Matching gifts#

Configuration variables#

Output variables#

Flow logic#

1. Pre-processing validation#

Refund without original donation check:

• Validates that refund transactions have an existing opportunity to refund against
• Sets error and terminates processing if refund attempted on new record

Anonymous donor resolution:

• Attempts to resolve existing donor from opportunity record
• Falls back to recurring donation contact if available
• Uses configured anonymous contact as final fallback

2. Donor relationship management#

Donor priority resolution:

1. Existing donor: Uses contact already on opportunity record
2. Recurring donor: Inherits contact from parent recurring donation
3. Anonymous donor: Uses configured anonymous contact ID
4. Provided donors: Uses DonorContact or DonorAccount from input

Account ID resolution:

• Calls helper subflow to determine appropriate AccountId
• Handles both direct account assignments and contact-derived accounts

3. Recurring donation integration#

Parent relationship processing:

• Generates platform key for parent recurring donation when ParentKey provided
• Looks up existing recurring donation record by platform key
• Sets npe03__Recurring_Donation__c relationship on opportunity

4. Matching gift processing#

Matching gift detection:

• Processes matched contact or account information
• Sets NPSP matching gift fields:
  • npsp__Matching_Gift_Employer__c: Employer name
  • npsp__Matching_Gift_Account__c: Employer account
  • npsp__Matching_Gift_Status__c: Set to "Received"

Matched record linking:

• Generates platform key for matched donation
• Links to original donation via npsp__Matching_Gift__c field

5. Date and currency processing#

Close date assignment:

• Skip: If Config_DonationSetCloseDate is false
• Start date: Converts StartDate to local date if provided
• Current date: Uses current date as fallback

Currency setting:

• Sets currency code using SetCurrencyValueFlowComponent
• Ensures consistent currency handling across multi-currency orgs

6. Status-based processing#

The flow handles six distinct donation statuses:

Success status#

• Stage: "Closed Won"
• Amount: Calculated amount (with optional fee deduction)
• Probability: 100%

Offline status#

• Configurable skip: Can be skipped via Config_IgnoreOfflineDonations
• Processing: Same as success when not skipped

Refund status#

Validation process:

1. Checks refund amount does not exceed original donation amount
2. Updates existing payment records with refund amount
3. Creates negative NPSP Payment record for refund
4. Adjusts opportunity amount by subtracting refund

Full vs partial refunds:

• Partial: Maintains "Closed Won" status
• Full: Changes to "Closed Lost" status

Failed status#

• Configurable skip: Can be skipped via Config_IgnoreFailedDonations
• Stage: "Declined" when processed
• Amount: Set to calculated amount

Pledge status#

• Stage: "Pledged"
• Amount: Set to calculated amount
• Use case: Committed donations not yet collected

Static status#

• Behaviour: Updates existing record amount only
• Use case: Where an amount has changed but there is no supporting detail

7. Amount and fee calculations#

Base amount calculation:

CalculatedAmount = IF(Config_DonationAmountSubtractFeePlatform, Amount - CalculatedFeePlatform, Amount)

Fee hierarchy:

• Platform fee: FeePlatformPublic -> FeePlatform (fallback)
• Fee fields set: Fee, FeePlatform, FeeGateway with respective taxes

8. NPSP payment integration#

Refund payment creation:

• Creates npe01__OppPayment__c record for refunds
• Sets negative payment amount
• Links to parent opportunity
• Uses refund transaction date

9. Privacy and anonymity#

Anonymous donation handling:

• Sets IsPrivate = true when Anonymous flag is set
• Respects Config_DonationSetAnonymousAsPrivate configuration
• Maintains donor privacy in public donation listings

10. Dynamic naming#

Naming pattern processing:

• Contact-based: Uses Config_DonationNameContact pattern
• Account-based: Uses Config_DonationNameAccount pattern
• Fallback: ASCII-encoded default patterns
• Pattern parser: Supports field merge syntax like {!Contact.Name}

Default patterns:

• Contact: {!Contact.Name} {!Amount} {!RecordType.Name} {!CloseDate}
• Account: {!Account.Name} {!Amount} {!RecordType.Name} {!CloseDate}

11. Record type and final assembly#

Record type assignment:

• Retrieves "Donation" record type ID via GetRecordTypeComponent
• Sets RecordTypeId on opportunity

Final field assignment:

• Campaign association
• Receipt number
• Platform key for future matching
• Description from message (if configured)

Error handling#

Comprehensive error tracking#

Error categories:

• Missing opportunity for refund processing
• Refund amount exceeding original donation
• Currency conflicts
• Invalid donor configurations

Detailed logging:

• Refund calculation details
• Skipped donation reasoning
• Fee calculation breakdowns
• Processing decision points

Dependencies#

Apex components#

• SetCurrencyValueFlowComponent: Currency management
• ConvertToLocalDateFlowComponent: Date timezone conversion
• movedata__GetRecordTypeComponent: Record type resolution
• movedata__NamePatternParserComponent: Dynamic name generation
• movedata__WriteToLogFlowComponent: Comprehensive logging

Subflows#

• MoveData_Donation_Donation_Key: Platform key generation
• MoveData_Donation_Recurring_Key: Recurring donation key generation
• MoveData_Donation_Helper_Get_Account_ID: Account resolution logic

Related articles#

• Donation platform key flow
• Donation record match flow
• Donation mapping flow (Non-Profit Cloud)
• Fields and objects