enhanced recurring donations upgrade guide...upgrade to enhanced recurringidonations...
TRANSCRIPT
Enhanced RecurringDonations Upgrade Guide
@salesforcedocs
Last updated: July 21, 2020
Salesforce.org and its logo are registered trademarks of Salesforce.com, inc. Other names used herein are
trademarks of Salesforce.com or their respective owners.
Contents
Contents
Overview of Enhanced Recurring Donations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1Why Enhanced Recurring Donations?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1Summary of Enhanced Recurring Donations Functionality. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2What About Legacy Recurring Donations?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Upgrade to Enhanced Recurring Donations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4Summary of Steps. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4Database Preparation Tasks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5Validate Migration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7Resolve Migration Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Enable Enhanced Recurring Donations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Deploy Metadata. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Migrate Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12Post Upgrade Tasks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14Adjust Field-Level Security for Recurring Donations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Create and Manage Recurring Donations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16Create an Open-Ended Recurring Donation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16Change an Open-Ended Recurring Donation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17Create a Fixed-Length Recurring Donation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19Change a Fixed-Length Recurring Donation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20Process Installment Opportunities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Process an Installment Opportunity Before or After the Next Donation Date. . . . . . . . . 23Enter Additional Donations for an Existing Recurring Donation. . . . . . . . . . . . . . . . . . . . . . . 24Close a Recurring Donation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25Delete a Recurring Donation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Appendix. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26Automatic Recurring Donations Naming. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26Change the Number of Installments Displayed in the Upcoming Installments
Component. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27Disable Rollups during Data Validation or Data Migration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27Map Custom Recurring Donation Status Values to a State. . . . . . . . . . . . . . . . . . . . . . . . . . . . 28Map Recurring Donation Fields to Opportunity Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29MetaDeploy Updates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Changes During Data Migration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34Entity Relationship Diagram. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Overview of Enhanced Recurring Donations Why Enhanced Recurring Donations?
Overview of Enhanced RecurringDonations
Why Enhanced Recurring Donations?Recurring donations are a dependable source of revenue for nonprofits, as donors whogive regularly are extremely important. They tend to continue giving for many years,and sometimes increase the amounts they give. When donors want to adjust how andwhen they give in response to changes in their lives, for example, if they want to pause orreschedule donations due to an unplanned event, you must be able to respond quickly andaccurately.
The Recurring Donations feature has existed in Nonprofit Success Pack (NPSP) for manyyears. In an effort to improve your experience when using it, and in partnership with ournonprofit user community, the Salesforce.org fundraising team embarked on a mission toreimagine Recurring Donations. Here's what you told us would make it better.
• More intuitive field labels, scheduling, and clarity between the different types of RecurringDonations.
• More predictable behaviors when changing Recurring Donation records. It should be veryclear when NPSP inserts, updates, or deletes related Opportunities.
• A simple way to update an existing Recurring Donation when donors want to changethe amount they give, the date when they donate, or other schedule details. Updating aRecurring Donation while leaving existing Opportunities in place improves reporting andmakes it possible to view recurring gifts in a single cohesive picture.
• Create only the installment Opportunity for the next donation date instead of manyrecords for future installments.
• A more durable code base that uses modern coding standards.
NoteIn this guide, we refer to the old Recurring Donations feature as "LegacyRecurring Donations" and the newly revised feature as "Enhanced RecurringDonations".
1
Overview of Enhanced Recurring Donations Summary of Enhanced Recurring Donations Functionality
Summary of Enhanced Recurring DonationsFunctionalityEnhanced Recurring Donations:
• Uses the same Recurring Donations object already in NPSP.
• Provides an in-app tool for upgrading to Enhanced Recurring Donations, includingmigrating your data to the new data model.
• Creates only one future, pledged Opportunity at a time per Recurring Donation. ThisOpportunity represents the next donation installment.
• Supports both open-ended and fixed-length Recurring Donations.
• Supports mapping field data from the Recurring Donation to related installmentOpportunities.
• Makes it easier to change an existing Recurring Donation without requiring that you closeor delete any records.
• Displays information about upcoming installment Opportunities and the active RecurringDonation schedule in two Lightning components.
• Retires some of the more confusing elements of the Legacy Recurring Donations datamodel.
What About Legacy Recurring Donations?Legacy Recurring Donations refers to the old Recurring Donations feature in NPSP. Once youupgrade, the Legacy Recurring Donations processing logic is replaced with the EnhancedRecurring Donations logic.
Q: What if I want to keep using Legacy Recurring Donations?
A: If you want to keep using Legacy Recurring Donations, don't upgrade to EnhancedRecurring Donations.
Q: What if I want to revert back to Legacy Recurring Donations at some point?
A: NPSP doesn't provide a way to switch back to Legacy Recurring Donations. Make sure thatyou're fully informed and ready to upgrade before you make the switch!
Q: Will Salesforce.org still support Legacy Recurring Donations?
2
Overview of Enhanced Recurring Donations What About Legacy Recurring Donations?
A: Yes! Legacy Recurring Donations isn't going anywhere and still exists in NPSP, should youdecide not to upgrade. That said, we aren't planning to develop any new features for LegacyRecurring Donations—all new development will focus on Enhanced Recurring Donations.
3
Upgrade to Enhanced Recurring Donations Summary of Steps
Upgrade to Enhanced RecurringDonations
Because Legacy Recurring Donations already exists in NPSP, you need to perform severalupgrade tasks and move your existing data to the Enhanced Recurring Donations model.
We've outlined the required tasks for you. Take your time and complete all of them.
Summary of Steps
ImportantDon't leave the upgrade partially complete! After you begin, plan to move throughall the upgrade tasks to completion. Give yourself plenty of time as the process cantake a while to finish.
1. Test in a sandbox first—To fully understand the upgrade process and the newfunctionality in Enhanced Recurring Donations, we strongly recommend that you test ina sandbox before upgrading your production org. You have these choices of sandboxesto test with:
a. Developer Sandbox—We recommend that you populate a Developer sandbox withat least some data from your production org. That way, you get a more realistic testof the upgrade process.
b. Full Sandbox—A Full sandbox is the best environment to test the upgrade processwith because a Full sandbox contains a copy of all your production data.
NoteWe don't recommend using a Partial Copy sandbox. Only a samplingof data from your production org gets copied into the Partial Copysandbox. The data sample is random and might be missing importantdata relationships (such as the lookup to Campaign). This can causeerrors during upgrade and complicate the testing process.
2. Database Preparation Tasks—To limit potential errors and to protect your data,complete these tasks to prepare your sandbox or production org for upgrade.
4
Upgrade to Enhanced Recurring Donations Database Preparation Tasks
3. Validate Migration—NPSP simulates migrating your existing data to the EnhancedRecurring Donations model and identifies errors.
4. Resolve Errors—If Validate Migration finds errors, resolve them before you continue.
5. Enable Enhanced Recurring Donations—This step replaces the Recurring Donationsprocessing logic with Enhanced Recurring Donations. Recurring Donations won'tfunction the same way once you enable Enhanced Recurring Donations.
CAUTIONNPSP doesn't provide a way to revert to Legacy Recurring Donations. Be surethat you're ready to enable Enhanced Recurring Donations!
6. Deploy Metadata—Use MetaDeploy to install new metadata for Enhanced RecurringDonations. MetaDeploy changes Recurring Donation:
a. Page layouts
b. Field labels
c. Field level security for the System Administrator and Standard user profiles
d. Picklist values
e. Help text
7. Migrate Data—Migrate your existing Recurring Donations data to the EnhancedRecurring Donations data model.
NoteFor details on how MetaDeploy and data migration affects your org, read theAppendix.
8. Post-Upgrade Tasks—Finish up with a few tasks before using Enhanced RecurringDonations.
Database Preparation TasksTo prepare for upgrade:
1. Enable Lightning Experience.
2. Enable and Deploy My Domain.
3. Enable Customizable Rollups.
5
Upgrade to Enhanced Recurring Donations Database Preparation Tasks
4. Assign these Apex classes to the user profile you'll use during the upgrade:
a. npsp.RD2_EnablementDelegate_CTRL
b. npsp.UTIL_BatchJobProgress_CTRL
c. npsp.RD2_StatusMappingSettings_CTRL
d. npsp.RD2_VisualizeScheduleController
NoteIf you don't see these Apex classes, Enable the Enhanced Profile UserInterface.
5. Disable your custom workflows, processes, validation rules, and triggers on theRecurring Donation, Opportunity, and Payment objects. This step is necessary toprevent errors during data migration. You don't need to disable NPSP workflows,triggers, etc.
6. Locate Legacy Recurring Donations that are connected to a Household Account andnot a Contact. Remove the Household Account and enter a Contact from the sameHousehold Account. After data migration, these Recurring Donations will be connectedto both the original Household Account and Contact.
7. Stop creating or editing Recurring Donations during the upgrade process. You mightneed to temporarily suspend:
a. User access to Recurring Donations (except for System Administrators)
b. Donation or payment processing integrations
c. Data import processes
8. Back up your database, including all Recurring Donations and their related records. Youcan skip this step if you're testing in a sandbox.
9. (Optional) Enable Field History Tracking for Recurring Donations. Field History Trackingallows you to track and report on field changes that occur during the data migrationstep.
10. Decide what to do with open Opportunities during data migration. Enhanced RecurringDonations use just one future Opportunity at a time. In NPSP Settings, under RecurringDonations, select a value in the Open Opportunity Behavior on RD Close setting (otherthan No_Action). The data migration will preserve the next open Opportunity in yourRecurring Donation schedule and apply your chosen behavior to the rest.
11. During the data migration step, NPSP converts Custom Installment Periods to theEnhanced Recurring Donations format. If you're using Custom Installment Periods,
6
Upgrade to Enhanced Recurring Donations Validate Migration
check to make sure that the Time Period Frequency is 20 or less. See Changes DuringMigration for more information.
ImportantIf you're using or intend to use 3rd party applications that integrate with theRecurring Donations, Opportunities, or Payments objects (such as for onlinedonations), please check with the vendor about compatibility with EnhancedRecurring Donations before upgrading.
Validate MigrationTo ensure that your migration runs error free, validate your data before you migrate it. If yourun into any errors during the test migration, fix them before you convert to the EnhancedRecurring Donations data model.
1. Go to NPSP Settings.
2. Click Recurring Donations > Upgrade to Enhanced Recurring Donations.
3. Click Validate Migration.
NoteProcessing a large number of records takes some time. If you'd like, you canleave the page and return later to check the progress.
4. After validation completes, you can view the results.
7
Upgrade to Enhanced Recurring Donations Resolve Migration Errors
If you see the green Success message, proceed to the next upgrade step.
If there are errors, resolve them before you continue. After you fix the errors, return to theupgrade page in NPSP Settings and validate the migration again.
If you need help with the errors, see Resolve Migration Errors, or post in the Power of UsHub.
Resolve Migration ErrorsDuring Validate Migration, you might encounter errors. Not to worry! NPSP provides an easyway to locate the records that caused the errors.
You'll know you have errors if the Validate Migration results look like this:
In this example, we see 3 Records Failed and a yellow Error message. The Completewith Errors Status means that the validation process finished processing all records anddetected at least one error.
To view the errors:
1. Refresh your browser to ensure all error logs appear.
2. Go to NPSP Settings > System Tools > Error Log.
3. Find the most recent error messages.
8
Upgrade to Enhanced Recurring Donations Resolve Migration Errors
In this example, a validation rule caused the errors. Someone in this org decided thatall Recurring Donations must have a related Campaign, but didn't make sure that all theexisting Recurring Donations had Campaigns before they activated the validation rule.
To fix the errors, you have some options.
• Copy and paste each Record URL in your browser to open the records, then add aCampaign to each Recurring Donation. This option is good if there are only a few recordsto fix.
• Run a report of Recurring Donations with a blank Campaign. Export the results to aspreadsheet, and add a Campaign Id for each row. Using Data Loader or a similar tool,update the records. This option is good if you have a lot of records to fix.
• Deactivate the validation rule. This option is good if you no longer need the validationrule.
This error is just one example of the types of errors you might encounter. Depending on thespecifics of your org, the steps required to fix the errors might vary.
After you fix all the errors, return to the Enhanced Recurring Donations upgrade page inNPSP Settings and validate the migration again. When validation completes without errors,proceed to the next upgrade step.
Resolve Error: "You must select a Contact associated with thisHousehold Account"1. Locate Legacy Recurring Donations that are connected to a Household Account and not
a Contact.
2. Remove the Household Account and enter a Contact from the same HouseholdAccount.
3. After data migration, these Recurring Donations will be connected to both the originalHousehold Account and Contact.
9
Upgrade to Enhanced Recurring Donations Enable Enhanced Recurring Donations
Resolve Error: "Installment Frequency is required. Enter avalue between 1 and 20".1. Go to NPSP Settings > Recurring Donations > Recurring Donation Custom
Installment Periods.
2. Delete any Custom Installment Periods that have a Time Period Frequency greater than20.
3. Create a new Custom Installment Period with the same name as the one you deleted.
4. Set the Time Period Frequency and Time Period Type such that they equal the CustomInstallment Period you deleted, but with Time Period Frequency between 1 and 20.For example, if your old Custom Installment Period had a Frequency of 26 and a PeriodType of Weeks, your new Custom Installment Period should have a Frequency of 6 anda Period Type of Months. The result being "twice per year" in both cases.
Enable Enhanced Recurring Donations
NoteNPSP doesn't provide a way to revert back to Legacy Recurring Donations. Be surethat you're ready to enable Enhanced Recurring Donations!
After you complete the preparation tasks and have validated your existing data with a testmigration, you're ready to enable Enhanced Recurring Donations. Enabling this settingchanges the processing logic for Recurring Donations to use Enhanced Recurring Donationslogic.
1. Go to NPSP Settings > Recurring Donations > Upgrade to Enhanced RecurringDonations.
2. Confirm that you have completed the preparation and validation tasks (1).
3. Enable Enhanced Recurring Donations (2).
That's all you need to do for this step. In the next step, you'll deploy metadata updates toyour organization.
10
Upgrade to Enhanced Recurring Donations Deploy Metadata
Deploy MetadataEnhanced Recurring Donations uses the existing Recurring Donation object plus someadditional elements. To install those elements, use our external MetaDeploy service.
1. Go to NPSP Settings > Recurring Donations > Upgrade to Enhanced RecurringDonations.
2. Click Launch MetaDeploy. MetaDeploy is an external service and opens in a newbrowser tab. When you're done with MetaDeploy, close it and return to your Salesforceorg to complete the upgrade process.
3. Click Log In to Start Pre-Install Validation, then choose whether you're installing in aProduction or Sandbox org.
4. Provide your Salesforce login credentials and click Log In.
NoteFor Sandbox login, remember to include the name of the Sandbox at the endof your username. For example, [email protected].
5. When prompted, Allow access.
6. Wait for the Pre-Install Validation to finish.
11
Upgrade to Enhanced Recurring Donations Migrate Data
7. Click Install.
8. Read the Product Terms of Use and Licenses. Select the confirmation checkbox thenclick Confirm.
9. Wait for the installation to finish.
10. Close MetaDeploy and return to your Salesforce org.
11. Confirm that you've installed the Enhanced Recurring Donations metadata.
NoteFor a complete list of the MetaDeploy changes, read MetaDeploy Updates inthe Appendix.
Now you're ready to migrate your existing Recurring Donations data to Enhanced RecurringDonations.
Migrate DataNow that you've enabled Enhanced Recurring Donations and deployed the supportingmetadata, it's time to migrate your existing data to Enhanced Recurring Donations.
ImportantThe data migration tool significantly changes your existing data. Read ChangesDuring Data Migration in the Appendix for a complete list of what's changed.Also, be sure to review Open Opportunity Behavior on RD Close in NPSPSettings. That setting determines how the migration tool handles future openOpportunities.
1. Go to NPSP Settings > Recurring Donations > Upgrade to Enhanced RecurringDonations.
12
Upgrade to Enhanced Recurring Donations Migrate Data
2. If any changes occurred in your org after you enabled Enhanced Recurring Donations,click Validate Migration to check for errors.
3. After validation, click Ready to Migrate, or click Skip Validation if you chose notto validate. Then click Run Migration. The data migration may take some time tocomplete, depending on how many Recurring Donation records are in your database.
NoteYou can stop the migration by clicking Stop Migration. However, any changesto your data to that point have already been committed and can't be rolledback. When you restart the migration process, the process resumes where itleft off. Until you complete the migration, some of your data will be in the oldmodel and some in the new model. If you've stopped a migration, you shouldcomplete it as soon as possible.
4. When the migration process completes, you can view the details. If the Status isComplete, you're all done! If the Status is Complete with Errors, see ResolveMigration Errors.
13
Upgrade to Enhanced Recurring Donations Post Upgrade Tasks
NoteIf you have a very large volume of Recurring Donation records to migrate to theEnhanced Recurring Donation model, you might want to disable rollups beforeyou run the data migration.
Post Upgrade TasksOnce you migrate your data, the upgrade process is complete. However, before yourorganization starts using Enhanced Recurring Donations, review these steps and completethe ones that apply to your org:
1. Turn on workflows, processes, validation rules, and triggers that you disabled prior toconversion.
2. Assign the Enhanced Recurring Donations page layout to all user profiles. Also add anycustom fields you have to the new layout.
3. Remove the old Recurring Donations page layout from all profiles.
4. Remove unused (deprecated) fields from the Recurring Donation related lists onAccount, Contact, and Campaign page layouts.
5. Verify that Automatic Recurring Donations Naming is enabled in custom settings.
6. The New Open Recurring Donation action on the Contact object doesn't include thecorrect fields to work with Enhanced Recurring Donations. Remove this action or createyour own that includes the correct fields.
7. Assign the NPSP Recurring Donation Lightning record page as the Org Default.
8. Assign the npsp.RD2_VisualizeScheduleController and npsp.RD2_EntryFormControllerApex classes to your custom profiles.
9. Adjust visibility of Recurring Donations fields on your custom profiles and permissionsets. See Adjust Field-Level Security for Recurring Donations.
10. Adjust Recurring Donations reports to work with the Enhanced Recurring Donationsdata model. For a list of data model changes, see the Appendix.
11. Adjust donation processing integrations and data import templates to match theEnhanced Recurring Donations data model.
12. Educate your staff about the new Recurring Donations functionality.
14
Upgrade to Enhanced Recurring Donations Adjust Field-Level Security for Recurring Donations
Adjust Field-Level Security for Recurring DonationsEnable these recommended field-level security settings for Recurring Donations on youruser profiles:
Field Label Field Name Security Setting
Account npe03__Organization__c Edit Access
Always use last day of month npsp__Always_Use_Last_Day_Of_Month__c No Access
Amount npe03__Amount__c Edit Access
Campaign npe03__Recurring_Donation_Campaign__c Edit Access
Closed Reason npsp__ClosedReason__c Edit Access
Contact npe03__Contact__c Edit Access
Current Year Value npsp__CurrentYearValue__c Read Access
Date Established npe03__Date_Established__c Edit Access
Day of Month npsp__Day_of_Month__c Edit Access
Donor Name npe03__Donor_Name__c Read Access
Effective Date npsp__StartDate__c Edit Access
Installment Amount npe03__Installment_Amount__c No Access
Installment Frequency npsp__InstallmentFrequency__c Edit Access
Installment Period npe03__Installment_Period__c Edit Access
Last Donation Date npe03__Last_Payment_Date__c Read Access
Next Donation Date npe03__Next_Payment_Date__c Read Access
Next Year Value npsp__NextYearValue__c Read Access
Number of Paid Installments npe03__Total_Paid_Installments__c Read Access
Number of Planned Installments npe03__Installments__c Edit Access
Open Ended Status npe03__Open_Ended_Status__c No Access
Payment Method npsp__PaymentMethod__c Edit Access
Recurring Donation Name Name Edit Access
Recurring Type npsp__RecurringType__c Edit Access
Schedule Type npe03__Schedule_Type__c No Access
Status npsp__Status__c Edit Access
Total npe03__Total__c No Access
Total Paid Amount npe03__Paid_Amount__c Read Access
15
Create and Manage Recurring Donations Create an Open-Ended Recurring Donation
Create and Manage RecurringDonations
Create an Open-Ended Recurring DonationOpen Recurring Donations are when a donor agrees to donate for an indefinite amount oftime.
In this example, a new monthly donor, Vera Reinhold, wants to donate $50 each month bycheck. She responded to a fundraising solicitation on April 5th, 2020, and will send a checkby the 10th of each month.
You can create a Vera Reinhold Contact, or use any existing Contact you'd like for thisexercise.
1. Click the Recurring Donations tab.
2. Click New.
3. Enter this information:
a. Donor Type = Contact
b. Contact = Vera Reinhold
c. Date Established = 4/5/2020
d. Amount = $50
e. Recurring Type = Open
f. Day of Month = 15
g. Payment Method = Check
h. Recurring Period = Monthly
i. Effective Date = 4/5/2020
4. Leave all other fields blank or with their default value.
5. Click Save.
The new Recurring Donation is now ready to track each monthly donation. NPSP auto-generates one open installment Opportunity for you at a time. If Vera's your donor, when
16
Create and Manage Recurring Donations Change an Open-Ended Recurring Donation
you receive her check, simply close the open Opportunity. During a nightly batch process,NPSP generates the next open Opportunity.
NoteYour administrator can change the Opportunity auto-creation behavior by going toNPSP Settings > Recurring Donations > Recurring Donations and changing theInstallment Opportunity Auto-Creation setting. The default behavior is to alwayscreate new installment Opportunities.
Change an Open-Ended Recurring DonationSometimes a donor asks that you change the amount, the day of the month the donationis processed, or perhaps the frequency of their Recurring Donation. Let's look at an exampleusing another monthly donor, Alan Hale.
Alan is a longtime donor who recently started earning more money and is ready to donatemore to his favorite charitable causes. Alan asks to increase his monthly giving from $50 to$100, starting on 6/1/2020.
Let's walk through how to make that update.
1. Locate or create a Recurring Donation that you'd like to update. In this example we'regoing to use Alan's Recurring Donation record.
2. Click Edit.
3. Update these fields:
a. Amount = $100
b. Effective Date = 6/1/2020
4. Click Save.
Take a look at the sidebar components on the Recurring Donation detail page.
17
Create and Manage Recurring Donations Change an Open-Ended Recurring Donation
Active Schedules provides details about the current and future schedules. You can seethat the Current Schedule is set to end on 5/31/2020, and the Future Schedule starts on6/1/2020.
Upcoming Installments displays a list of planned installments. Notice that the currentschedule of $50 per month runs until 6/1/2020, when the amount increases to $100 permonth.
18
Create and Manage Recurring Donations Create a Fixed-Length Recurring Donation
Create a Fixed-Length Recurring DonationFixed Recurring Donations are Recurring Donations where the donor agrees to donate for aspecific number of installments.
In this example, a new donor, Ron Morimura, wants to donate $1250 each quarter (every 3months) for one year starting on 4/15/2020. He signed up for this Recurring Donation at afundraising gala on December 10th 2019 and wants to pay using bank transfers.
You can create a Ron Morimura Contact, or use any existing Contact you'd like for thisexercise.
1. Click the Recurring Donations tab.
2. Click New.
19
Create and Manage Recurring Donations Change a Fixed-Length Recurring Donation
3. Enter this information.
a. Donor Type = Contact
b. Contact = Ron Morimura
c. Date Established = 12/10/2019
d. Amount = $1250
e. Recurring Type = Fixed
f. Number of Planned Installments = 4
g. Recurring Period = Advanced
h. Every = 3
i. Installment Period = Months
j. Day of Month = 15
k. Effective Date = 4/15/2020
l. Payment Method = ACH/EFT
4. Leave all other fields blank or with their default value.
5. Click Save.
The new Recurring Donation is now ready to track each quarterly donation. NPSP auto-generates one open installment Opportunity for you at a time. If Ron was your donor, youwould wait until you receive his bank transfer, and then close the open Opportunity. Duringa nightly batch process, NPSP generates the next open Opportunity.
Change a Fixed-Length Recurring DonationOften a donor chooses to set up a fixed-length donation because they have a target amountor duration that they want to donate for. Sometimes, though, your donor might ask that youchange the amount, date, or length of their donation.
Let's look at an example. Ron Morimura signed up to donate $1250 per quarter for one year(totaling $5000 for the year). However, soon after he initially signed up to donate, he calledand asked to extend his giving for a second year.
Let's walk through how to make that update.
1. Locate a Recurring Donation that you'd like to update. In this example we're going touse Ron's Recurring Donation record.
2. Click Edit.
20
Create and Manage Recurring Donations Process Installment Opportunities
3. Update these fields:
a. Number of Planned Installments = 8 (previously it was 4)
b. Effective Date = 7/1/2020 (or whatever the current date is)
4. Click Save.
Before the update, Ron's Recurring Donation showed four Upcoming Installments.
After the update, Ron's Recurring Donation now shows eight Upcoming Installments.
Process Installment OpportunitiesVera just sent in her first check. Let's process the installment Opportunity.
1. On Vera's Recurring Donations, click the Related tab and find the Opportunities relatedlist.
2. Click the Opportunity record Vera Reinhold (1) 1/10/2020.
21
Create and Manage Recurring Donations Process Installment Opportunities
3. Click the Closed stage in the path bar, then click Select Closed Stage.
4. Select Closed Won. Your Closed Won stage might be labeled something else (such asPosted).
5. Click Save.
With this Opportunity closed, Vera's payment is recorded. On the Recurring Donationrecord, Total Paid Amount and Number of Paid Installments show that the first installmentof $50 has been paid.
During a nightly batch process NPSP generates the next installment, in this case, for2/10/2020. To the right of the Recurring Donations details, you can see a list of the nexttwelve installments.
Upcoming Installments is a calculated display of installment Opportunities based on thefield data on the Recurring Donation. If you change field data on an installment Opportunity,those changes aren't reflected in the Upcoming Installments visualization.
22
Create and Manage Recurring Donations Process an Installment Opportunity Before or After the Next
Donation Date
NoteIf you want to adjust the number of installments shown in Upcoming Installments,your administrator can edit the record page and adjust the component settings.
Process an Installment Opportunity Before or Afterthe Next Donation DateSometimes a donor might pay their monthly installment a little early or a little late. That'sperfectly fine, of course, but there are a couple of things to consider:
• If the Close Date is within three days of the Next Donation Date, NPSP doesn't create aninstallment for the same month.
• If those dates are more than three days apart, NPSP generates a new installment for thesame month.
This functionality exists to prevent duplicate installments.
Let's look at an example scenario.
1. Your donor's Recurring Donation has a Next Donation Date of 4/15/2020, but theysend their payment on 4/12/2020.
2. When you update the installment Opportunity's Stage to Closed Won, the Close Dateupdates to 4/12/2020.
3. In this case, NPSP doesn't generate the next installment for 4/15/2020 because4/12/2020 falls within three days of the Next Donation Date. Instead, the nextinstallment is generated for 5/15/2020.
Here's another example.
1. Your donor's Recurring Donation has a Next Donation Date of 6/15/2020, but theysend their payment on 6/1/2020.
2. When you update the installment Opportunity's Stage to Closed Won, the Close Dateupdates to 6/1/2020.
3. In this case, NPSP generates the next installment for 6/15/2020 because 6/1/2020is more than three days from the Next Donation Date. This produces two installmentOpportunities for the month of June.
23
Create and Manage Recurring Donations Enter Additional Donations for an Existing Recurring Donation
NoteYour administrator can adjust the range of days that NPSP considers when anOpportunity matches the intended schedule using the Next Donation Date MatchRange in NPSP Settings > Recurring Donations. The default value is three days.
Enter Additional Donations for an ExistingRecurring DonationNPSP creates installment Opportunities according to the schedule information on theRecurring Donation record. Sometimes though, a donor might make another donation inaddition to their regular donation. That's great! Here's all you need to do:
1. Create an Opportunity for the additional donation.
2. Enter the Primary Contact, Amount, Close Date, and Stage, plus any additionalinformation.
3. In the Recurring Donation field, add your donor's existing Recurring Donation record.
4. Save the record.
NoteWhen you have two or more future, open Opportunities, only the earliest one getsupdated when you update the Recurring Donation schedule data. For example,let's say you have:
1. An open Opportunity with a Close Date of 6/28, and an Amount of $100.
2. A second open Opportunity with a Close Date of 6/29, and an Amount of$100.
24
Create and Manage Recurring Donations Close a Recurring Donation
3. When you update the Recurring Donation Amount to $200, only the 6/28Opportunity's Amount gets updated.
Close a Recurring DonationSometimes a donor requests that you end their Recurring Donation. Other times, you mightlose contact with a donor and can't get current payment information. Here's how to close aRecurring Donation.
1. Locate the Recurring Donation you wish to close.
2. Click Close Recurring Donation.
3. Select a Status Reason and an End Date.
4. Click Save.
NoteAdministrators: NPSP updates the Stage for open installment Opportunitiesaccording to the behavior defined in NPSP Settings > Recurring Donations >Open Opportunity Behavior on RD Close.
Delete a Recurring DonationTo delete a Recurring Donation, find the record to delete and click Delete.
When you delete a Recurring Donation, NPSP deletes the associated Opportunities. If thereare any associated Closed Won Opportunities, you won't be able to delete the RecurringDonation. You must delete the Closed Won Opportunities before you can delete theRecurring Donation.
25
Appendix Automatic Recurring Donations Naming
Appendix
Automatic Recurring Donations NamingBy default, NPSP names your Recurring Donations automatically. Here's how it works:
1. Go to the Recurring Donations tab and click New.
2. Fill out the required fields (Amount, Donor Type, Recurring Period, etc.).
3. Click Save.
Once you save the record, NPSP creates the Recurring Donation Name using this format:
“[DonorName] [Amount] - Recurring”
[DonorName] is Contact Name when the Donor Type is Contact, or the Account Namewhen the Donor Type is Account and the Account is an Organizational Account. Let's look atsome examples.
• If you enter a new $100 Recurring Donation for Barbara Levy, the name becomes:
– Barbara Levy $100 - Recurring
• If you enter a new $500 Recurring Donation for Universal Containers, the name becomes:
– Universal Containers $500 - Recurring
Change Automatic Naming FormatA system administrator can change the default naming format in NPSP Settings. Here's how:
1. Go to NPSP Settings > Recurring Donations > Recurring Donations.
2. Find Recurring Donation Name Format and select your desired format.
3. Click Save.
Disable Automatic NamingIf you have your own naming convention that you'd rather use, you can disable AutomaticRecurring Donation Naming. When you disable naming, users will see the RecurringDonation Name field in the record entry and edit screens.
1. Go to NPSP Settings > Recurring Donations > Recurring Donations.
26
Appendix Change the Number of Installments Displayed in the
Upcoming Installments Component
2. Find Recurring Donation Name Format and select Disable Auto Naming.
3. Click Save.
Change the Number of Installments Displayed inthe Upcoming Installments ComponentTo adjust the number of installments shown in Upcoming Installments, edit the record pageand adjust the component settings.
1. On a Recurring Donation record, click the gear icon then click Edit Page.
2. Click the Upcoming Installments component, then update Number of installmentsto display. 12 is the default value.
3. Click Save.
NoteUpcoming Installments is a calculated display of installment Opportunitiesbased on the field data on the Recurring Donation. If you change field data onan upcoming Opportunity, those changes won't be reflected in the UpcomingInstallments visualization.
Disable Rollups during Data Validation or DataMigrationIf you have a very large volume of Recurring Donation records to migrate to the EnhancedRecurring Donation model, you might want to disable rollups before you validate or run thedata migration.
1. In Setup, enter Custom Settings in Quick Find and push enter.
27
Appendix Map Custom Recurring Donation Status Values to a State
2. Click Custom Settings.
3. Click Manage next to Recurring Donations Settings.
4. Click Edit.
5. Select Disable CRLP When Creating Installments.
6. Click Save.
Now your rollups calculate in a nightly batch instead of at the same time you run the validateor migration process.
When you have completed the upgrade to Enhanced Recurring Donations, return to CustomSettings and deselect Disable CRLP When Creating Installments.
NoteWhat is a "large volume" of records in Salesforce? 100,000? 500,000? There's noprecise definition. As a general rule, if your organization stores over one millionrecords, and certainly several million, then your organization is probably a largedata volume org.
Map Custom Recurring Donation Status Values toa State
NoteYour user profile must have access to the RD2_StatusMappingSettings_CTRL apexclass to use Status to State mapping.
When you create custom picklist values for Recurring Donation Status, you must map themto a State so that NPSP can process records with those custom Status values.
State describes NPSP Recurring Donation processing behaviors. The following States areavailable:
• Active: The donor is actively donating. NPSP creates installment Opportunities as definedby the Recurring Donation schedule.
• Lapsed: The donor isn't making donations as expected, but NPSP still creates installmentOpportunities as defined by the Recurring Donation schedule.
• Closed: The donor stopped making donations for this Recurring Donation. NPSP doesn'tcreate any new installment Opportunities.
28
Appendix Map Recurring Donation Fields to Opportunity Fields
ImportantIf you don't map your custom Status, you won't be able to create or updateRecurring Donations that use those custom Statuses.
Here's how this works in practice. Let's say you create a Status called Expired Card totrack when a donor's credit card has expired. You don't want to immediately close outthe Recurring Donation because you want to ask the donor if they have updated cardinformation first. In this example, the State behavior you want NPSP to use is Lapsed. There'sgoing to be a lapse in the donor's giving until you can obtain new card information.
To map a custom Status value to a State:
1. Go to NPSP Settings > NPSP Settings > Recurring Donations > Status to StateMapping.
2. Click Edit.
3. Assign a State to each of your custom Status values.
4. Click Save.
NoteEnhanced Recurring Donations includes standard Status values that are alreadymapped to their corresponding State: Active, Lapsed, and Closed. These standardStatus values are required for Enhanced Recurring Donations, so don't removethem from your org!
Map Recurring Donation Fields to OpportunityFields
Standard Field MappingWhen NPSP creates installment Opportunity records for a Recurring Donation, it copies thevalues of several fields from the Recurring Donation onto the Opportunity records. This isa big time saver, as it means you don't have to manually enter values for all those fields oneach Opportunity record.
The following table describes how NPSP maps fields from the Recurring Donation to itsinstallment Opportunity records when the Recurring Donation is first created.
29
Appendix Map Recurring Donation Fields to Opportunity Fields
Recurring Donation Field Opportunity Field Explanation
Created By Created By NPSP copies the value of theCreated By field from the RecurringDonation to the Opportunity.
Owner Owner NPSP copies the value of theOwner field from the RecurringDonation to the Opportunity.
Account Account Name NPSP copies the Account from theRecurring Donation to the AccountName field on the Opportunity.
Contact Primary Contact NPSP copies the value of theContact field on the RecurringDonation to the Primary Contactfield on the Opportunity.
Next Donation Date Close Date NPSP copies the Next DonationDate from the Recurring Donationto the Close Date on theOpportunity.
Amount Amount NPSP copies the Amount from theRecurring Donation to the Amounton the Opportunity.
Campaign Primary Campaign Source NPSP copies the Campaign fromthe Recurring Donation to thePrimary Campaign Source on theOpportunity.
CurrencyISOCode CurrencyISOCode NPSP copies the CurrencyISOCodefrom the Recurring Donation tothe CurrencyISOCode on theOpportunity.
The default Stage for Opportunities in a Recurring Donation is Pledged. This default canbe changed by altering the Recurring Donation Stage Name Custom Label. For moreinformation, see Customizing Labels.
Custom Field MappingIt's great that NPSP automatically copies key information from standard Recurring Donationfields to Opportunity fields. But what if you want to map custom fields as well? You're inluck because NPSP lets you do just that! For more information, see Map Recurring DonationFields to Custom Opportunity Fields.
30
Appendix MetaDeploy Updates
MetaDeploy UpdatesMetaDeploy makes these changes to your Salesforce instance.
• New Enhanced Recurring Donations Page Layout
– This new layout is assigned as the default layout for the System Administrator andStandard User profiles. You should assign this layout to all your custom profiles.
– The layout is specific to Enhanced Recurring Donations. All deprecated fields havebeen removed from this layout.
• Updated NPSP Recurring Donations Lightning Record Page
– The new page includes Lightning components that display a list of upcominginstallments and a list of the active schedules on the Recurring Donation.
• New Recurring Donation Record Entry and Edit Interface
– MetaDeploy overrides the standard New and Edit buttons to use thenpsp:Rd2_EntryForm Lightning component on the Recurring Donations object.
• Help Text Changes
– npsp__StartDate__c
– Old: (null)
– New: The date that new or updated schedule information (Amount, Day of Month,etc.) for this Recurring Donation takes effect. The default is the current date.
– npsp__Day_of_Month__c
– Old: Sets future monthly, custom monthly, or quarterly donation installments to theselected day of the month, regardless of Next Donation Date. NOTE: If the Alwaysuse last day of month checkbox is selected, it supersedes the Day of Month value.
– New: Sets the specific day of the month for future installment Opportunities whenthe Installment Period is Monthly. If you select 29 or 30, the installment date will bethe last day of the month for months that don't have that many days.
– npe03__Installment_Period__c
– Old: How often you'll receive the donations. NOTE: Changing the installment periodfor an existing Fixed-Length Recurring Donation may result in the loss and re-
31
Appendix MetaDeploy Updates
creation of open Opportunities. Any data associated with those opportunities maybe lost.
– New: Defines the installment schedule of this Recurring Donation along withInstallment Frequency. For example, if Installment Period is Monthly and InstallmentFrequency is 3, the schedule is defined as "every 3 months."
– npe03__Next_Payment_Date__c
– Old: The date on which you want the next donation to occur. This date alsodetermines the date of all future donations.
– New: Calculated automatically using the active Recurring Schedule(s). Read only.Note that the calculation in Enhanced Recurring Donations uses a trigger and Apexcode. Legacy Recurring Donations used a rollup.
– npe03_Amount__c
– Old: (null)
– New: The amount for each installment Opportunity.
– npe03_Date_Established__c
– Old: (null)
– New: The initial inception date for this Recurring Donation. The default is the currentdate.
– npe03__Last_Payment_Date__c
– Old: Do Not Enter. NPSP calculates this value automatically based on the last time achild donation was marked Posted.
– New: NPSP calculates this value automatically based on the last time an installmentOpportunity was marked paid (read only).
– npe03__Paid_Amount__c
– Old: Do Not Enter. NPSP calculates this value automatically as donations are madeand marked Posted.
– New: The total amount paid on this Recurring Donation. Calculated automatically asthe total amount of all Closed/Won installment Opportunities (read only).
– npe03__Total_Paid_Installments__c
– Old: Do Not Enter. NPSP calculates this value automatically as donations are madeand marked Posted.
– New: Total number of installment Opportunities paid on this Recurring Donation(read only).
32
Appendix MetaDeploy Updates
– npsp__CurrentYearValue__c
– Old: (null)
– New: This Recurring Donation's total amount for the current calendar or fiscal year(read only). Includes Closed Won Opportunities plus future installments for the restof the year.
– npsp__NextYearValue__c
– Old: (null)
– New: This Recurring Donation's total expected amount for the next calendar or fiscalyear (read only).
• Picklist Value Changes
– npsp__Day_of_Month__c
– New: "Last Day of Month"
– Inactivated: "29", "30", "31"
– npe03__Installment_Period__c
– New: (nothing new)
– Inactivated: "Quarterly"
• Field Label Changes—"Deprecated" is appended to these field labels:
– npe03__Installment_Amount__c
– npe03__Open_Ended_Status__c
– npe03__Schedule_Type__c
– npe03__Total__c
– npsp__Always_Use_Last_Day_Of_Month__c
33
Appendix Changes During Data Migration
• Field-Level Security Changes—These existing fields are all changed to Read Only for theSystem Administrator and Standard User profiles:
– npe03__Paid_Amount__c
– npe03__Total_Paid_Installments__c
– npe03__Installment_Amount__c
– npe03__Open_Ended_Status__c
– npe03__Schedule_Type__c
– npe03__Total__c
– npsp__Always_Use_Last_Day_Of_Month__c
– npsp__CurrentYearValue__c
– npsp__NextYearValue__c
• Field-Level Security Changes—These new fields are set to Editable for the SystemAdministrator and Standard User profiles:
– npsp__Day_of_Month__c
– npsp__InstallmentFrequency__c
– npsp__RecurringType__c
– npsp__PaymentMethod__c
– npsp__StartDate__c
– npsp__Status__c
– npsp__ClosedReason__c
– npe03__Installments__c
Changes During Data MigrationNPSP makes the following changes during the data migration step of the EnhancedRecurring Donations upgrade.
Recurring Donations Custom SettingsThe migration process copies the value of the custom labelnpe03.RecurringDonationStageName to a new custom setting,npsp__InstallmentOppStageName__c.
34
Appendix Changes During Data Migration
Custom Installment PeriodsCustom Installment Periods are configured in NPSP Settings > Recurring Donations >Recurring Donation Custom Installment Periods. The migration process converts CustomInstallment Periods to Recurring Donation field data.
Custom Installment Period Field Recurring Donation Field Data Migration Details
Time Period Frequency Installment Frequency Time Period Frequency must bebetween 1 and 20 otherwise thedata migration process will reportan error.
Time Period Type Installment Period Days converts to Daily. Weeksconverts to Weekly. Monthsconverts to Monthly. Years convertsto Yearly.
Recurring Donation ObjectThe migration process makes these changes to the Recurring Donation object.
Field Label Field Name Data Migration Details
Account npe03__Organization__c No change to data.
Always Use Last Day of Month npsp__Always_Use_Last_Day_Of_Month__c No change to data.
Amount npe03__Amount__c For Recurring Donationswhere Open Ended Status= None and Schedule Type= Divide By or is null, theAmount is changed to thevalue in Installment Amount.For example, a RecurringDonation Amount of $2400where there are 12 plannedinstallments results in anAmount of $200 ($2400 / 12= $200).
Otherwise, the Amountremains unchanged.
Campaign npe03__Recurring_Donation_Campaign__c No change to data.
Closed Reason npsp__ClosedReason__c No change to data.
Contact npe03__Contact__c No change to data.
Current Year Value npsp__CurrentYearValue__c All Recurring Donations areset to 0. The value for thisfield is then recalculatedduring a nightly batch.
35
Appendix Changes During Data Migration
Field Label Field Name Data Migration Details
Date Established npe03__Date_Established__c No change to data.
Day of Month npsp__Day_of_Month__c If Always Use Last Day OfMonth is selected, or the DayOf Month field value is 29,30, or 31, then the value inthis field will be "Last Day ofMonth." Otherwise, the valueis unchanged.
Donor Name npe03__Donor_Name__c No change to data.
Effective Date npsp__StartDate__c Effective Date is changedto the date of the earliestOpportunity (based onClose Date). If there are noOpportunities, then DateEstablished is used.
Installment Amount npe03__Installment_Amount__c No change to data.
Installment Frequency npsp__InstallmentFrequency__c If the Installment Periodis "Quarterly," InstallmentFrequency is set to 3. If theInstallment Period is anyother value, InstallmentFrequency is set to 1. If theInstallment Frequency is aCustom Installment Period,Installment Frequency iscopied from Time PeriodFrequency.
Installment Period npe03__Installment_Period__c If the Installment Periodis "Quarterly," then theInstallment Period is setto "Monthly." All othervalues are left as is. If theInstallment Period is aCustom Installment Period,the value is copied from TimePeriod Type.
Last Donation Date npe03__Last_Payment_Date__c No change to data.
Next Donation Date npe03__Next_Payment_Date__c No change to data.
Next Year Value npsp__NextYearValue__c All Recurring Donations areset to 0. The value for thisfield is then recalculatedduring a nightly batch.
Number of Paid Installments npe03__Total_Paid_Installments__c No change to data.
36
Appendix Changes During Data Migration
Field Label Field Name Data Migration Details
Number of PlannedInstallments
npe03__Installments__c When Open Ended Status is"Open", Number of PlannedInstallments is updated tonull.
Otherwise, the original valuefor Number of PlannedInstallments remainsunchanged.
Open Ended Status npe03__Open_Ended_Status__c No change to data.
Payment Method npsp__PaymentMethod__c No change to data.
Recurring Type npsp__RecurringType__c When Open Ended Statusis "Open", Recurring Type isupdated to "Open".
When Open Ended Status is"None" or is null, RecurringType is updated to "Fixed".
Status npsp__Status__c If the Open Ended Statusfield value is "Closed," thenStatus is updated to "Closed."Otherwise, Status is updatedto "Active."
Schedule Type npe03__Schedule_Type__c No change to data.
Total npe03__Total__c No change to data.
Total Paid Amount npe03__Paid_Amount__c No change to data.
Opportunity ObjectThe migration process makes these changes to Opportunity records related to RecurringDonations.
Where the parent Recurring Donation's Open Ended Status is "Open":
• The next open installment Opportunity in the Recurring Donation schedule remainsunchanged.
• All closed Opportunities remain unchanged.
37
Appendix Entity Relationship Diagram
• All additional, open Opportunities are updated based on the value of Open OpportunityBehavior on RD Close in NPSP Settings. The choices in that setting are:
– Update the Stage to Closed Lost
– Delete the Opportunities
NoteEnhanced Recurring Donations doesn't support more than one future openOpportunity, so you can't select "No_Action" in the Open OpportunityBehavior setting. You must choose one of the other options.
Where the parent Recurring Donation's Open Ended Status is "None" or is null:
• All Opportunities, regardless of Stage, remain unchanged.
Entity Relationship Diagram
38