Salesforce Connector – Control Panel
To open the Control Panel, using the Apps menu, locate the Engaging Networks Connector App.
The control panel provides quick access to relevant documentation and areas of the tool.
Engaging Networks Staging Records
If inside Engaging Networks’ Salesforce settings “Sync Transaction data to Salesforce” is enabled, every morning (+-2am EDT) transactional data will be pushed to the Salesforce org.
Engaging Networks Staging Records represent supporters actions that have occurred from the previous day. Examples could include Petitions (PET), Email to Target (ETT), Fundraising Credit Single (FCS) and Fundraising Credit Recurring (FCR) etc. based on the modules being used in the Engaging Networks account.
For more on transaction types, check this article.
This gives an integrator all they need to understand how to access pieces of data. For example, getting the donation amount or tracking value from an FCS row.
These objects thus represent a ‘staging’ queue which the Mapping Rules use to extract the information in order to map to various objects in Salesforce.
SFDC Contact Id and SFDC Campaign Id are passed from Engaging Networks to allow staging records information to be associated with the relevant Contact and Campaigns.
As Contact syncing is handled by Engaging Networks, the Engaging Networks Staging Record fields are transactionally specific. The only supporter information included is First Name, Last Name and Email.
Included in the package are a number of Views, to help isolate the different transactions types on offer.
Advocacy Txns Unprocessed highlights staging records whose Transaction Type is PET or ETT or CTT or TWT and whose Processed Flag is false.
Mapping Rules
Mapping Rules are the core of the transaction processing engine. They provide the lookup rules for staging objects and the directives of writing staging data to the respective Salesforce objects.
A mapping rule allows the following to be done: “find staging objects that are single credit card gifts and then write them as opportunities, linking them to a Contact” etc.
Engaging Networks offers a collection of mappings, on installation, that form the base of the NPSP integration.
However, you have complete control over the mappings and which objects should represent the data from Engaging Networks.
For example, if you do not wish to represent Advocacy transactions as CampaignMembers and use a custom object instead, or if your organisation is not using NPSP – this can be achieved through the Mapping Rules.
Default Mappings
Engaging Networks offers a set of default mappings geared for the NonProfit Success Pack installation. Implementers are encouraged to customize these default mappings to their particular NPSP configurations.
Mappings can be installed through the Engaging Networks dashboard, under Transaction Mappings.
For reference, JSON representations of the mappings can be found at the Engaging Networks GitHub repository: https://github.com/EngagingNetworks/salesforce-connector-mappings
Included in the Engaging Networks dashboard are options of exporting and importing Mapping Rules as JSON. This offers a Salesforce admin the ability to easily create backups and/or methods of transferring ‘tested’ rules from Sandbox to Production.
As areas for improvement arise related to the default Mapping Rules, Engaging Networks will release new versions. Updated Mapping Rules will only apply if you install new mappings or delete current ones and install them again.
If your Mapping Rules are functioning fine, there is no need to utilize any new or updated mappings that we release.
The current out-of-the-box Mapping Rules related to Recurring Donations are tied to the Enhanced Recurring Donation data model with NPSP. If you wish to use these mappings, ensure Enhanced Recurring Donations are turned on in your NPSP settings.
Contact Top Up (template)
Transaction Types: All
Find Staging objects with empty SFDC Contact Ids.
Because the Contact Sync runs every twenty minutes, it is expected that all transactions written to the ENSR table will have a corresponding SFDC Contact Id. Most fundraising mappings rely on this Contact Id, for example to attach a new Opportunity to the donor. In the event an ENSR arrives with no SFDC Contact Id, this mapping creates a simple contact (First Name, Last Name, and Email only) so the mappings can proceed. This new Contact should be picked up by the contact sync and filled in with the remaining supporter details (address, etc.) shortly after creation. (This previously ran on Fundraising transactions only, but has been generalized to all transactions with a 'Group by' ensuring the mapping avoids creating duplicate Contacts)
Advocacy – Create Campaign Member (template)
Transaction Types: PET, CTT, ETT, TWT
If an advocacy page is configured with SFDC Campaign Id, this mapping rule adds participants to the Campaign. The Campaign Member status is set to Responded.
This particular mapping only runs if the Contact is not a pre-existing member of the Campaign. Salesforce does not permit adding a Contact twice to the same Campaign. A trigger installed on the ENSR object assists: if both Campaign Id and Contact Id are populated when the ENSR is created, the trigger checks whether a Campaign Member already exists for this Contact/Campaign combination. If a match is found, the trigger writes the Campaign Member Id to the ENSR. This way, this “create” mapping avoids creating a duplicate Campaign Member by checking the SFDC CampaignMember Id field.
If multiple unprocessed staging records are present for the same Contact Id - Campaign Id pair, this mapping rule does a 'group by' ensuring the contact is added to the campaign just once. This can happen for ETT, for example, where one action with 4 targets can result in 4 distinct staging record rows.
Advocacy – Update Existing Campaign Member (template)
Transaction Types: PET, CTT, ETT, TWT
This mapping is a companion to “Advocacy – Create Campaign Member” above. In the event a Campaign Member already exists, this mapping updates the status of this pre-existing Campaign Member status to “responded”.
If multiple unprocessed staging records are present for the same Contact Id - Campaign Id pair, this mapping rule does a 'group by' ensuring the contact is added to the campaign just once. This can happen for ETT, for example, where one action with 4 targets can result in 4 distinct staging record rows.
Engagement – Create Campaign Member (template)
Transaction Types: SVY, EMS, UNS, ECF
If an engagement page is configured with SFDC Campaign Id, this mapping rule adds participants to the Campaign. The Campaign Member status is set to Responded.
Engagement – Update Existing Campaign Member (template)
Transaction Types: SVY, EMS, UNS, ECF
This mapping is a companion to “Engagement – Create Campaign Member” above. In the event a Campaign Member already exists, this mapping updates the status of this pre-existing Campaign Member status to “responded”.
Email Open – Create Campaign Member (template)
Transaction Types: EBC, MBC
If an outgoing email (broadcast or marketing automation) is configured with SFDC Campaign Id, this mapping rule adds email openers to the Campaign. The Campaign Member status is set to Responded.
Email Open – Update Existing Campaign Member (template)
Transaction Types: EBC, MBC
This mapping is a companion to “Email Open – Create Campaign Member” above. In the event a Campaign Member already exists, this mapping updates the status of this pre-existing Campaign Member status to “responded”.
Fundraising Single – Opportunity (template)
Transaction Types: FCS, FBS, FOC
The first of two mappings for processing one-time (single) donations, this mapping builds out an Opportunity for each successful fundraising transaction. By default, the mapping includes standard fields such as Amount and Close Date. It also writes the EN Tracking and Appeal Codes to open up the possibility for analysis through Salesforce reports. The gateway reference (EN Transaction Id field) preserves an audit trail between Salesforce Opportunities, Engaging Networks Transactions, and your payment gateway.
The mapping relies on the following NPSP components. If any of these are not used in your Salesforce org, you will need to adjust the mapping rule accordingly:
Opportunity Naming Rules are active
Stage picklist has a value named “Posted”
You are using the NPSP Payments object
Fundraising Single – Payment (template)
Transaction Types: FCS, FBS, FOC
The second of two mappings for processing one-time (single) donations, this mapping builds out a Payment object for each successful fundraising transaction. The mapping marks the payment as “paid”, records the Payment Method (Credit Card or ACH/EFT), and records the gateway reference as Check/Reference Number to preserve clear audit trails.
If your Salesforce org uses NPSP's GAU Allocation object, you might need to write a third mapping rule for this purpose. If you are using NPSP Default Allocations, you can simply place a GAU Allocation on the Campaign that is referenced by the field. No mapping changes are needed. If you are not using Default Allocations, you can use the "direct my gift" tagged field (Transaction Data 20) as either a hidden field, or as a picklist, to hold the fund designation. You will need to build an additional mapping rule to handle the allocation, and ensure it is properly chained into the Opportunity - Payment - Allocation chain (don't mark as complete until all 3 elements have run.)
Fundraising Recurring - New RD for Imported Transactions
Transaction Types: FCR, FBR, where Transaction Data 4 = .00
When recurring transactions are migrated/imported into Engaging Networks, an initial $0.00 transaction is created indicating that the gift has been imported. This mapping rule uses the data stored on these initial rows to create the Recurring Gift that can be updated the next time the transaction processes. It functions very similarly to the Fundraising Recurring – New RD mapping rule (see below) but uses different criteria to find imported transactions.
Fundraising Recurring – New RD (template)
Transaction Types: FCR, FBR, where Transaction Data 11 is empty
The first of three mappings for processing a *new* Recurring Donation commitment. This mapping rule creates an NPSP Recurring Donation object, with open-ended status (no fixed end date) and Monthly/Quarterly/Annual frequency. The gateway id (Data 2) is stored on the Recurring Donation (EN Parent Transaction Id) as this “parent transaction id” will be used for processing all subsequent recurring charges.
NPSP automatically creates a series of “pledged” Opportunities matching the anticipated payment schedule. The first of these “pledged” opportunities will be marked as “posted” in a subsequent mapping rule.
The default mappings are configured to work with NPSP's Enhanced Recurring Donations model, with Future Pledged Opportunities configured to create at least 1 pledged Opportunity. If you have turned off Pledged Opportunities in NPSP settings, you will need to modify the "Fundraising Recurring - Opportunity" mapping to create a new Opportunity instead of looking up & updating an existing Opportunity.
Fundraising Recurring – Lookup & Update RD – success (template)
Transaction Types: FCR, FBR, where Transaction Data 11 is not empty
The first of three mappings for processing a *subsequent* recurring transaction. This mapping rule uses the “parent transaction id” of the incoming transactional data (Transaction Data 11) to look up the Recurring Donation that was created when the commitment was first initiated. The parent is written to the SFDC Recurring Donation Id field. This mapping also updates the parent Recurring Donation with the latest “amount” and “day of month” that is configured with Engaging Networks to ensure NPSP and EN payment schedules remain in sync, and ensures the RD status is set to "Active".
Fundraising Recurring – Opportunity (template)
Transaction Types: FCR, FBR
The second of three mappings for both *new* and *subsequent* recurring transactions. This mapping rule looks up a “pledged” Opportunity in the parent RD’s payment schedule, and updates the status from “pledged” to “posted”. It also updates the actual Close Date for the Opportunity (sometimes this varies from the schedule date, for example if the card was declined at first but succeeded on a retry), the actual Amount processed, the tracking values/appeal codes, and the gateway Id for the transaction.
For a pledged Opportunity to be identified and posted, the scheduled Close Date for the Opportunity must be on or before the actual processing date of the transaction. This is specified in the Matching Rule filter.
Fundraising Recurring – Payment (template)
Transaction Types: FCR, FBR
The third of three mappings for both *new* and *subsequent* recurring transactions. This mapping rule attaches a Payment to the Opportunity that was changed from “pledged” to “posted”. If the pledged Opportunity already had a Payment on it, the mapping updates that existing payment instead of creating a new one. The Payment is marked as “paid” and both the Payment Method and Gateway Id are captured.
Fundraising Recurring – Lookup & Update RD – change (template)
Transaction Types: FCR, FBR, status = change/reject
Run when a recurring transaction record has status of "change" or "reject", this mapping helps keep NPSP's Recurring Donations in sync with what is happening on the Engaging Networks side. This mapping:
Updates an RD from "Active" to "Lapsed" if Engaging Networks has automatically suspended payments due to 3+ declines on the credit card.
Updates an RD from "Active" to "Closed" if the Engaging Networks donation has been cancelled
Updates an RD from "Active" to "Closed" if the Engaging Networks donation has been paused
Updates the Day of Month and Amount if either of these have changed in Engaging Networks (e.g. if donor upgrades their monthly gift)
Fundraising Recurring - Card Update (template)
Transaction Types: FRU
When a donor updates their payment card information via the Supporter Hub, or a user updates the donor's payment card information, the Parent Transaction Id changes for the recurring sequence. The FRU transaction allows us to look up the RD that is attached to the prior Parent Transaction Id (Transaction Data 11) and write in the new Parent Transaction Id (Transaction Data 02) so future transactions can be properly matched up to the correct parent RD.
Fundraising In Memoriam (template)
Transaction Types: FIM
When a tribute gift is processed in Engaging Networks, two transaction rows are generated. The first row is the financial detail (FCS/FBS) which is processed using the same mapping as non-tribute gifts, “Fundraising Single – Opportunity.” The second row is the In Memorium transaction (FIM).
This mapping looks up the Opportunity that was created through the prior “Fundraising Single – Opportunity” rule, and appends Tribute information to this Opportunity per the FIM transaction row. The sample mapping writes:
Tribute Type = Honor
Honoree Name
Notification Recipient Name
Notification Recipient Information (Email and/or Mailing Address) – this field is populated via a formula field on the ENSR (“Additional Note”) which draws all the relevant data into one common field
This mapping is a sample of processing tribute gifts. This rule will need to be customized for your situation, as Tribute setup varies significantly between Engaging Networks configurations. For example, you likely offer Tribute Type = Memory as well, and you might offer the donor different options for sending an eCard, sending an email notification, or requesting that a letter be mailed by your organization on the donor’s behalf. You will need to update this mapping to reflect the options you expose to your donors, as well as the fields you have used to build your form.
A common scenario is to use the “Reason for Gift” tagged field (Transaction Data 10) to indicate In Memory / In Honor selection, and the “Tribute Options” tagged field (Transaction Data 9) for the donor to select how they want a notification delivered to the honoree/designate.
Event Purchase – Opportunity (template)
Transaction Types: ECS, EBS, ECC
This mapping rule mirrors “Fundraising Single – Opportunity”. See above. Note that the event mapping records the ticket purchaser (ECS/EBS/ECC) but not individual attendees (ETA). It captures “free” tickets as $0 opportunities.
You will likely update this mapping rule to include a custom Record Type from your Salesforce org corresponding to ticket purchases.
Event Purchase – Payment (template)
Transaction Types: ECS, EBS, ECC
This mapping rule mirrors “Fundraising Single – Payment”. See above.
Refund – Opportunity (template)
Transaction Types: RFD, EFD
This mapping creates a negative opportunity corresponding to a refund processed by Engaging Networks. It does not alter the original opportunity.
Refund – Payment (template)
Transaction Types: RFD, EFD
This mapping creates a negative payment corresponding to a refund processed by Engaging Networks. It does not alter the original payment.
Peer-to-Peer Mapping Templates
The Peer-to specific mapping rules are designed to work with Salesforce's Campaign Hierarchy Structure, and take advantage of summary functionality.
Each Campaign will summarize both the campaign members and opportunities related to it in addition to the summary of each child campaign's totals.
Please note that the limit of hierarchy for Salesforce is 5 levels. As templated, including Organizations and Teams, this hierarchy structure is 4 levels.
As with all Engaging Networks mappings, they can be customized to work with your Salesforce configuration.
If you are not using Organizations or Teams, excluding relevant templates from installation will not affect the other mapping templates.
Peer-to-Peer Site - Create Parent Campaign - PSTE (template)
Transaction Types: PSTE
This mapping finds a Campaign record, using the Page Id (EN Campaign Id), or creates a new Campaign record if none is found, and updates information. This Campaign represents the Site Donation Page, and is the parent campaign for the hierarchy.
Peer-to-Peer Site - Create Organization Page Campaign - PFOC (template)
Transaction Types: PFOC
This mapping finds a Campaign record, using the Page Id (EN Campaign Id), or creates a new Campaign record if none is found, and updates information. This Campaign represents the Organization Donation page, which both Team and Fundraiser Pages can be childed to.
Peer-to-Peer Site - Create Team Page Campaign - PFTC (template)
Transaction Types: PFTC
This mapping finds a Campaign record, using the Page Id (EN Campaign Id), or creates a new Campaign record if none is found, and updates information. This Campaign represents the Team Donation page, which Fundraiser Pages can be childed to.
Peer-to-Peer Site - Create Individual Page Campaign - PFRP (template)
Transaction Types: PFRP
This mapping finds a Campaign record, using the Page Id (EN Campaign Id), or creates a new Campaign record if none is found, and updates information. This Campaign represents the Fundraiser Donation page, and can be childed to any of the other Campaign types.
Peer-to-Peer - Update Fundraiser's Team Campaign - Remove (PFTE) (template)
Transaction Types: PFTE
This type represents the Engaging Networks action of removing a Fundraiser from a Team. This mapping finds a Campaign record, using the Page Id (EN Campaign Id), and sets the Parent Campaign back to the Site level campaign, removing it and all related opportunities to a new place in the hierarchy directly below the Site Campaign.
Peer-to-Peer - Update Org Campaign of Fundraiser/Team - Remove (PFOE) (template)
Transaction Types: PFOE
This type represents the Engaging Networks action of removing a Fundraiser or Team from an Organization. This mapping finds a Campaign record, using the Page Id (EN Campaign Id), and sets the Parent Campaign back to the Site level campaign, removing it and all related opportunities to a new place in the hierarchy directly below the Site Campaign.
Peer-to-Peer - Update Org Campaign of Fundraiser/Team - Add (PFOA) (template)
Transaction Types: PFOA
This type represents the Engaging Networks action of adding a Fundraiser or Team to an Organization. This mapping finds a Campaign record, using the Page Id (EN Campaign Id), and sets the Parent Campaign to the Organization campaign, moving it and all related opportunities to a new place in the hierarchy directly below the Organization Campaign.
Peer-to-Peer - Update Fundraiser's Team Campaign - Add (PFTA) (template)
Transaction Types: PFOA
This type represents the Engaging Networks action of adding a Fundraiser or Team to an Organization. This mapping finds a Campaign record, using the Page Id (EN Campaign Id), and sets the Parent Campaign to the Organization campaign, moving it and all related opportunities to a new place in the hierarchy directly below the Organization Campaign.
Peer-to-Peer - Update Campaign Page (TPPU, IPPU, OPPU) (template)
Transaction Types: TPPU, IPPU, OPPU
This mapping updates existing campaign records (name, goal, etc.) to match Engaging Networks pages. If multiple changes occur in one day, it will group changes and choose the most recent record for updating the campaign, which will have all final updated data.
Peer-to-Peer Single Donation - Opportunity (template)
Transaction Types: PFCS, PFBS, PPAY, PACS
This mapping rule mirrors the Fundraising Single - Opportunity (see above). This mapping rule finds the appropriate campaign depending on the Page the donation came through (Using EN Campaign Id) rather than pulling in the Campaign Id set on a page.
Peer-to-Peer Single Donation - Payment (template)
Transaction Types: PFCS, PFBS, PPAY, PACS
This mapping rule mirrors the Fundraising Single - Payment (see above).
Peer-to-Peer - Fundraising Recurring - New RD (template)
Transaction Types: PFCR, PFBR
This mapping rule mirrors the Fundraising Recurring - Payment (see above).
Peer-to-Peer - Fundraising Recurring - Opportunity (template)
Transaction Types: PFCR, PFBR
This mapping rule mirrors the Fundraising Recurring - Opportunity (see above).
Peer-to-Peer - Fundraising Recurring - Payment (template)
Transaction Types: PFCR, PFBR
This mapping rule mirrors the Fundraising Recurring - Payment (see above).
Peer-to-Peer - Fundraising In Memoriam (template)
Transaction Types: PFIM
This mapping rule mirrors the Fundraising in Memoriam mapping. (see above).
Peer-to-Peer - Refund - Create Reverse Opportunity (template)
Transaction Types: PRFD
This mapping rule mirrors the Refund - Create Reverse Opportunity (see above).
Peer-to-Peer - Refund - Create Reverse Payment (template)
Transaction Types: PRFD
This mapping rule mirrors the Refund - Create Reverse Payment (see above).
“Group By” Items
Many of our Mapping Rules contain a section called “Group Staging Records By” which is a relatively new feature and therefore might not exist on the current iteration of your Mapping Rules.
The “Group Staging Records By” terms are meant to help alleviate Campaign Member errors caused by transactions with multiple rows for the same action (for example, Email to Target actions where multiple transaction rows get created per supporter). This “Group By” functionality groups staging records by a certain object so the whole matching batch gets processed at the same time, preventing errors.
If you find that you are running into errors caused by these types of transactions, the updated Mapping Rules including “Group Staging Records By” should be able to help.
Creating Custom Mappings
If you wish to alter or create new mappings, the Mappings Rules area allows control of this administration.
Jobs Schedules
Three schedulable jobs are available in the Engaging Networks Connector.
ENSR Cleanup
Delete X days old Engaging Networks Staging Records
Log Cleanup
Delete X days old Engaging Networks Logs
Process Mapping Rules
Process ‘active’ Mappings Rules, in order of priority. At this time, please only utilize the ‘daily’ option and schedule processing for after 3am EDT.
Logs
Included in the package are a number of Views, to help isolate the different Logs that are generated. The following events trigger Logs to be generated :
Engaging Networks Contact Push
On pushing Contact information, Engaging Networks will create a Log record denoting Success and Failures count.
There is a similar screen inside Engaging Networks and allows review of ‘failures’.
Engaging Networks Contact Pull
On pulling Contact information, Engaging Networks will create a Log record denoting Record Count
Engaging Networks Transaction Push
On pushing Transactional information, Engaging Networks will create a Log record denoting Success and Failures count.
Processing Errors
There are two ways for Mapping Rules to run: either by invoking the ‘Manually Process’ option, under Mapping Rules, or when the ‘Mapping Rule Process’ job is scheduled and processing occurs.
In both occasions, if an apex error is thrown a Log record will be generated.
Look out for the description as to why there has been a failure. If you are building out new Mapping Rules and testing, it may be that a field permission is not allowing the object to be created for example.