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.
Mappings Rules
Mappings 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.
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”.
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)
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 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.
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.
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.
“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.