Recurring mapping flow
Note
This flow is self-documenting and should be viewed within Salesforce (Setup > Process Automations > Flows). This document is to support working through a visual flow. The flow commentary in this document was generated with AI assistance.
Overview#
Flow name: MoveData_Donation_Recurring_Mapping Label: [MoveData] Donation: Recurring - Mapping Type: Auto-Launched Flow Template API version: 60.0 Status: Active
This flow transforms recurring donation data from external platforms into Salesforce NPSP records, managing donor relationships, currency validation, status mapping, frequency configuration, and Enhanced Recurring Donations (RD2) compatibility.
Purpose#
The flow processes incoming recurring donation data and maps it to appropriate Salesforce NPSP fields while handling:
- Donor relationship management (Contact/Account assignment)
- Anonymous donor configuration and lookup
- Currency validation and conflict detection for existing records
- Recurring donation status mapping
- Fee calculation and amount adjustments
- Start date and next payment date conversions to local timezone
- Campaign associations
- Frequency and installment configuration (legacy and RD2)
- Day of month calculation
- Platform key tracking
Salesforce fields#
This flow interacts with the NPSP Recurring Donation object and its related fields. Below is a comprehensive mapping of all fields utilised:
| Object | Field API name | Field type | Purpose in flow |
|---|---|---|---|
| npe03__Recurring_Donation__c | Id | ID | Unique record identifier |
| CurrencyIsoCode | Picklist (if multi-currency enabled) | Currency code for the recurring donation | |
| npe03__Amount__c | Currency | Recurring donation amount per installment | |
| npe03__Contact__c | Lookup to Contact | Primary contact for individual donors | |
| npe03__Organization__c | Lookup to Account | Organization for institutional donors | |
| npe03__Date_Established__c | Date | Date the recurring donation was established | |
| npe03__Installment_Period__c | Picklist | Frequency of recurring payments | |
| npe03__Next_Payment_Date__c | Date | Date of the next expected payment | |
| npe03__Open_Ended_Status__c | Picklist | Whether the recurring donation has an end date | |
| npe03__Recurring_Donation_Campaign__c | Lookup to Campaign | Associated campaign for the recurring donation | |
| npsp__Status__c | Picklist | Current status of the recurring donation | |
| npsp__StartDate__c | Date | Enhanced Recurring Donations start date | |
| npsp__InstallmentFrequency__c | Number | Frequency multiplier for Enhanced RD | |
| npsp__Day_of_Month__c | Text | Preferred day of month for payments | |
| md_npsp_pack__Platform_Key__c | Text (100) | Platform identifier for matching | |
| npe03__Recurring_Donations_Settings__c | npsp__IsRecurringDonations2Enabled__c | Checkbox | Indicates if Enhanced Recurring Donations enabled |
Input variables#
Core recurring donation data#
| Variable | Type | Required | Description |
|---|---|---|---|
Record |
npe03__Recurring_Donation__c | Yes | The Recurring Donation record being processed |
Amount |
Currency | No | Recurring donation amount per installment |
StartDate |
DateTime | No | Recurring donation start date/time |
EndDate |
DateTime | No | Recurring donation end date/time |
NextPaymentDate |
DateTime | No | Next expected payment date |
Status |
String | No | External platform status (active/cancelled/complete/failed/paused) |
Frequency |
String | No | Payment frequency (yearly/quarterly/monthly/weekly/advanced) |
Day |
Number | No | Day of month for payments |
CurrencyType |
String | No | ISO currency code |
Platform integration#
| Variable | Type | Description |
|---|---|---|
PlatformKey |
String | Unique platform identifier for tracking |
Key |
String | External platform's unique identifier |
Related records#
| Variable | Type | Description |
|---|---|---|
DonorContact |
Contact SObject | Associated contact for the recurring donation |
DonorAccount |
Account SObject | Associated account for the recurring donation |
DonationCampaign |
Campaign SObject | Associated campaign |
Enhanced Recurring Donations (RD2) support#
| Variable | Type | Description |
|---|---|---|
FrequencyInterval |
String | Interval type (week/month/year) for advanced frequency |
FrequencyUnit |
Number | Number of intervals between payments |
Fee calculation#
| Variable | Type | Description |
|---|---|---|
FeePlatform |
Currency | Platform processing fee |
FeePlatformPublic |
Currency | Public platform fee |
Donation_FeePlatform |
Currency | Associated donation platform fee |
Donation_FeePlatformPublic |
Currency | Associated donation public fee |
Configuration variables#
| Variable | Type | Default | Description |
|---|---|---|---|
IsNewRecord |
Boolean | - | Flag indicating if this is a new record |
Config_AnonymousContactId |
String | - | ID of anonymous contact for anonymous donations |
Config_DonationAmountSubtractFeePlatform |
Boolean | false | Whether to subtract platform fees from amount |
Config_RecurringSuppressCampaign |
Boolean | false | Skip campaign assignment |
Config_RecurringSuppressStartDate |
Boolean | false | Skip start date setting |
Config_RecurringSuppressDateEstablished |
Boolean | false | Skip date established setting |
Config_RecurringSuppressDay |
Boolean | false | Skip day of month setting |
Config_RecurringSuppressNextPayment |
Boolean | false | Skip next payment date setting |
Config_RecurringIgnoreStartDateNotEmpty |
Boolean | false | Only set start date if empty |
Config_RecurringIgnoreDateEstNotEmpty |
Boolean | false | Only set date established if empty |
Config_RecurringIgnoreDayNotEmpty |
Boolean | false | Only set day of month if empty |
Output variables#
| Variable | Type | Description |
|---|---|---|
Record |
npe03__Recurring_Donation__c | Updated recurring donation record |
Logs |
MoveDataLogEntry[] | Processing logs |
LogsJSON |
String | JSON representation of logs |
Flow logic#
1. Record evaluation#
The flow determines whether it is processing a new or existing record:
- New record: Proceeds directly to donor determination
- Existing record: Checks currency consistency to prevent NPSP conflicts
2. Currency validation#
For existing records, validates currency consistency:
- Retrieves existing currency code using
GetValueComponent - Compares with incoming currency type
- Conflict detected: Logs error and ends processing (NPSP does not support currency changes)
- No conflict: Proceeds with processing
3. Donor assignment#
The flow determines the primary donor relationship using this hierarchy:
| Priority | Condition | Action |
|---|---|---|
| 1 | Both Contact and Account missing + Anonymous Contact configured | Use anonymous contact |
| 2 | Contact provided (Account missing) | Assign to Contact |
| 3 | Account provided | Assign to Account |
| 4 | Existing relationships present | Preserve existing assignments |
4. Currency setting#
Sets the currency code on the record using the SetCurrencyValueFlowComponent.
5. Date processing#
Converts DateTime inputs to local dates:
- Start date: Converted using
ConvertToLocalDateFlowComponent - Used for both
npsp__StartDate__candnpe03__Date_Established__c - Configuration: Respects
Config_RecurringSuppressStartDate,Config_RecurringSuppressDateEstablished,Config_RecurringIgnoreStartDateNotEmpty, andConfig_RecurringIgnoreDateEstNotEmpty
6. Amount calculation#
Calculates the final amount using the formula:
CalculatedAmount = IF(Config_DonationAmountSubtractFeePlatform, Amount - FeePlatform, Amount)
Fee calculation hierarchy:
FeePlatformPublic(if provided)Donation_FeePlatformPublic(if provided)FeePlatform(if provided)Donation_FeePlatform(if provided)- 0 (default)
7. Status mapping#
Maps external platform statuses to NPSP values:
| External status | NPSP status |
|---|---|
| cancelled | Closed |
| complete | Closed |
| failed | Lapsed |
| paused | Paused |
| (other/success) | Active |
8. Campaign association#
Campaign assignment logic:
- Skip: If
Config_RecurringSuppressCampaignis true - Assign: If
DonationCampaignis provided and has valid ID - Ignore: Otherwise
9. Next payment date processing#
Sets the next payment date if:
NextPaymentDateis provided- Date is greater than or equal to current date
Config_RecurringSuppressNextPaymentis false- Either no existing next payment date OR calculated date is newer
10. Frequency and installment configuration#
The flow supports both legacy and Enhanced Recurring Donations (RD2):
Standard frequencies#
| Frequency | Installment period | Notes |
|---|---|---|
| yearly | Yearly | - |
| weekly | Weekly | - |
| monthly | Monthly | Default fallback |
| quarterly | Quarterly (legacy) or Monthly with frequency 3 (RD2) | Depends on RD2 enablement |
Advanced frequency (RD2 only)#
When Frequency is "advanced", uses FrequencyInterval and FrequencyUnit:
| FrequencyInterval | Installment period | InstallmentFrequency |
|---|---|---|
| week | Weekly | FrequencyUnit |
| year | Yearly | FrequencyUnit |
| month (default) | Monthly | FrequencyUnit |
11. Day of month calculation#
Sets npsp__Day_of_Month__c using this hierarchy:
- Day from
NextPaymentDate(if provided) Dayinput parameter (if provided)- Day from
StartDate(if provided)
12. Open ended status#
Sets npe03__Open_Ended_Status__c to "Open" if the field is currently null.
13. Platform key assignment#
Sets Platform_Key__c field for future record matching.
Enhanced Recurring Donations (RD2) support#
Detection logic#
- Queries
npe03__Recurring_Donations_Settings__c.npsp__IsRecurringDonations2Enabled__c - Adjusts frequency mapping based on enablement
RD2-specific mappings#
- Uses
npsp__InstallmentFrequency__cfor interval counts - Maps quarterly to monthly with frequency of 3
- Supports advanced frequency patterns
Error handling#
Currency conflict handling#
- Detects mismatched currencies between donations and recurring donations
- Logs detailed error message
- Ends processing to prevent NPSP conflicts
Protection mechanisms#
- Respects configuration flags for suppressing field updates
- Handles null values gracefully throughout the flow
- Preserves existing field values when configured
Dependencies#
movedata__GetValueComponent(Apex action)movedata__WriteToLogFlowComponent(Apex action)SetCurrencyValueFlowComponent(Apex action)ConvertToLocalDateFlowComponent(Apex action)