Skip to main content

NPSP Opportunity Installment Field Mapper

This article explains the NPSP-for-PaymentHub Opportunity Installment Field Mapper.


FinDock does not and cannot guarantee that every possible configuration of the NPSP Opportunity Installment Field Mapper leads to a working system. Sub-optimal or wrong configurations can slow performance, breaking recursions or standard functionality. Every change to the field mapping configuration must follow standard test procedures.

What is the NPSP Opportunity Installment Field Mapper?#

The NPSP Opportunity Installment Field Mapper enables detailed customization of how Installment and Opportunity records are synced at field level. This eliminates the need for custom triggers or process builders to sync fields between Installment and Opportunity.

Enabling the Field Mapper#

The new field mapper is auto-enabled for new orgs and cannot be disabled by a customer. This section applies only to existing orgs.

To enable the Opportunity Installment Field Mapper for existing orgs:

  1. Launch the FinDock app, and on the Setup tab, scroll down to the Source Connectors section and click on PaymentHub-for-NPSP.
  2. Click on the Opportunity Installment Field Mapping tab and click the toggle to enable.

After enabling, the toggle disappears. In the unlikely case that this feature needs to be disabled, please contact FinDock Support. Enabling this feature changed the behavior of the following fields:

  • AccountId
  • Primary_Contact
  • Amount
  • Payment_Method
  • Payment_Profile
  • Payment_Processor
  • Opportunity.Target
  • Due_Date

Synchronization is triggered bidirectionally instead of only on opportunity changes. This change may impact customizations, so we advise performing regression testing after enabling.

Create custom mappings#

Below is a sample screenshot of the Field Mapper. The numbers correspond to the steps in the following procedure.

NPSP Opportunity Installment Field Mapper

To add a custom Installment - Opportunity mapping:

  1. On the Opportunity Installment Field Mapping tab, add a custom mapping by clicking the Add Record button.
  2. Select the Opportunity field to map. All fields can be selected, except formula fields and the Managed by FinDock fields (see below).
  3. Select the sync direction:
    • ←: Only sync on Installment changes.
    • →: Only sync on Opportunity changes.
    • ⇆: Sync both on Installment and Opportunity changes.
  4. Select the Installment field to map to the selected Opportunity field. All fields can be selected, except formula fields and the Managed by FinDock fields (see below).
  5. Select the type:
    • Always: Sync both on inserts and updates.
    • Only On Insert: Sync only on insert.
  6. Click Save to save new custom mappings or changes to existing custom mappings.
  7. Use the Delete button to delete a custom mapping.
  8. Use the Back button to navigate back to FinDock setup.

Opportunity Record Type#

Also the Opportunity Record Type can be set using the field mapper, by:

  • Under Opportunity Field, select Record Type Id
  • Under Installment Field select any text field. This text field must contain either the Id (“0123O0000005qtx”) or the Name (e.g. “NPSP_Default”) of the Opportunity Record Type. Only Direction ← (Installment to Opportunity) and Type “Only On Insert” are supported.

Managed by FinDock#

Some fields are managed by FinDock, meaning these mappings are included in the FinDock solution and cannot be further customized.

Opportunity FieldDirectionInstallment FieldRemarks
Primary Contact<=>Contact
Payment Method<=>Payment Method
Payment Profile<=>Payment Profile
Payment Processor<=>Payment Processor
Campaign Id<=>Originating Campaign
Generated Payment Reference<=>Generated Payment Reference
Custom Payment Reference<=>Custom Payment Reference
Recurring Payment Reference<=>Recurring Payment Reference
StageName<=See remarksIf the installment is created with status Collected, then the NPSP default closed status is used. For all other installment status options, NPSP status Pledged is used. With installment update changes, the FinDock status mapping is used.
CloseDate<=See remarksIf the installment status is Collected, then the last collection date from the installment is used. In all other cases, the installment due date is used.
Opportunity Name<=See remarksDonation + Opportunity CloseDate
See remarks=>StatusWhen an installment is created from an opportunity and the opportunity is closed, then the mapping between Installment status and Opportunity stage is used. Otherwise, the status is New. With opportunity updates, the FinDock status mapping is used.
See remarks=>SourceAlways PaymentHub-for-NPSP
See remarksRecord TypeAlways Receivable
Close date=>Original Due DateOnly on insert of Opportunity
Close Date=>Due DateOnly when opportunity stage not closed
ID=>Opportunity IdOnly on insert of Opportunity