How does it work?
The GiveSmart Fundraise Salesforce integration is a daily automated API sync, which syncs newly settled transactions to your Salesforce instance as Opportunities.
Once the field mappings are established and the sync activated, the integration is intended to run in the background with minimal intervention needed. In general, this integration is a lightweight solution which will automatically create new Opportunities for GiveSmart Fundraise transactions, match to existing Contacts by email or create new Contacts if there is no email match.
Getting Started
If you have the Salesforce CRM Integration included in your plan, reach out to your GiveSmart Customer Success Manager, who will notify the integrations team to reach out with next steps to the point of contact you specify. Otherwise, contact your Customer Success Manager for more information on how to add Salesforce integration support to your GiveSmart plan.
Retrieving your API Key
If you are an Admin user in GiveSmart Fundraise, you can retrieve your Private API key.
Note: Only users with Admin privileges will be able to access the API information in GiveSmart Fundraise.
Once the integration app is installed in Salesforce, you can update the API key from Setup > Search: Custom Metadata Types > Locate: MobileCause API Configuration > Manage Records > Actions: Edit
Replace the 'changeme' value in the API Key field > Save
Mapping Editor
The Global Form is the only supported mapping template and the only template you will need to configure for the integration, as it will be applied to all transactions synced from GiveSmart Fundraise.
The Global Form should always remain as the default mapping, as you can add any new field mappings to this template without the need for additional templates.
Note: The Default Form Mapping cannot be deleted. Though the integration app allows you to create custom mapping templates which can to link to different forms, the Global Form is the only supported mapping. All mapping can be accomplished using this template to ensure uniformity (see: Mapping Custom Fields below).
Custom templates are not supported.
Set Up Campaign Mapping
To map the SFDC Primary Campaign Source to any GiveSmart Fundraise form, first, create a Hidden Form Element titled "sf_campaign" on the form. The Hidden Field's Value should be the Salesforce Campaign ID, exactly as it appears in Salesforce. Full steps here.
After Saving, here's what the hidden element will look like when editing your form.
TIP: You may follow these same steps to map a form to the SFDC Record Type, using “sf_record_type” as the hidden field label, and the record type ID as the Hidden Field Value.
Mapping Custom Fields
To map a GiveSmart Fundraise custom field to an SFDC field on the Opportunity, first, ensure that the field exists on at least one GiveSmart Fundraise form. Next, enter the Reporting Label of the field in the Custom Fields box when editing your Global Form template.
When adding Custom Fields, use the following format:
- All lowercase characters
Replace any spaces with underscores
Additional fields to be separated by a comma
For example, in the custom fields box, a GiveSmart field titled "Choose Fund To Support:" should read as:
choose_fund_to_support:
Next, select Update Form Mapping on the right-hand side.
This will make the custom field available to select in the Source Field drop down when adding a new field mapping.
On-Demand Sync
To sync historical donations, or to sync a new transaction for testing purposes, the "Request from API" option in the On-Demand Sync tab can be used to execute a manual sync. Most transaction sync jobs take about a minute to complete.
Note: The Request from API option will initiate a new sync job to pick up any settled monetary transactions within the date range you specify. Just be sure to only click this button once (avoid double-clicking).
Activating the Sync
Select Schedule Daily Sync from the On-Demand Sync tab.
Note: The daily sync will run as the Salesforce user that schedules it, so just make sure this is activated by a user that you do not anticipate deactivating in order to prevent any disruptions to the daily sync.
Testing the Sync
When setting up the integration, it's imperative to test the sync using a real donation to confirm data can be successfully retrieved from GiveSmart and allow the new Opportunity to be created in Salesforce. This section breaks down how to test your sync during the initial setup, and how to test any changes made to your field mappings.
Note: There is no test credit card option for GiveSmart. The Salesforce sync can only be tested with eligible monetary donations (minimum $1) submitted through a GiveSmart Fundraise form.
Testing the Sync - During Setup
If you do not have any settled donations in your account to sync yet, you may enter a small donation through one of your GiveSmart Fundraise forms. This would need to be a true monetary donation paid by credit card, for example. Once the payment has fully settled (often after 1 day), it is eligible to sync to Salesforce.
In your GiveSmart Fundraise reporting, refer to the "Billing Status" reporting column for sync eligibility.
Use the On-Demand Sync controls as described above to choose the transaction date and request the data.
Testing the Sync - Mapping Changes
Scenario 1: You've made changes to your GiveSmart form (e.g. added a new custom field), and updated your Global Form mapping in Salesforce to map this new source field on the Opportunity object. You'd like to sync a gift to make sure the new data will be mapped as expected.
The best practice is to submit a new test transaction through the GiveSmart form and include test data in the new field, if the field is non-hidden (for example, if a field mapping for "Honoree Name" was added, enter a name into this field when completing the gift).
Once the payment has fully settled (often after 1 day), it is eligible to sync to Salesforce. You can either manually sync it using the On-Demand Sync controls, or wait for it to come over in the automated daily sync (if activated).
Scenario 2: You already have a settled transaction (or a former test transaction) that was submitted with data that has now been mapped to Salesforce. You'd like to re-sync this transaction to confirm the data will be mapped as expected.
Note: this scenario would not include transactions submitted prior to a field being created/added to the form that has since been mapped to Salesforce.
Using "Honoree Name" as an example, let's say a donation was made with an Honoree Name provided through the form field prior to being mapped in the Global Form. You've updated your Global Form to add the GiveSmart source field mapping to the Honoree Name field on the Salesforce Opportunity, and would like to re-sync the transaction to confirm that the Honoree Name will be applied to the new Opportunity created.
In the Salesforce app head to the tab titled “MobileCause Transactions.” Here you can sort by “All” to return all transactions retrieved from GiveSmart Fundraise with their Sync Status, Date, Name, Opportunity, and other details.
From that report, select the MC Transaction ID for the donation you'd like to re-sync/test with:
From this page, edit the Sync Status field from Complete to Unprocessed > Save:
Reprocess Transactions
After updating the Sync Status field on the transaction detail page, navigate to the On-Demand Sync tab where you should see the transaction appear in the Unprocessed/Failed queue ready to be actioned.
Select "Process MC Transactions" at the top to re-run the transaction. Be careful not to double-click this button.
Note: This will create a new Opportunity linked in the Transaction Detail, where you can observe if the changes took effect. You may locate and delete the original Opportunity, if needed.
Sync Troubleshooting
It's possible that an edit to a field mapping, internal change to Salesforce, or user change in GiveSmart can inadvertently cause transactions to fail to sync to Salesforce. The scenarios outlined below detail the steps to take should an interruption to the sync occur.
Sync Jobs are Pending/Incomplete
If you notice that transactions have not been syncing, and see the latest transaction jobs in the On-Demand Sync tab are titled "Job Pending - Requesting Report ID", this means there is a disconnect with the API that can be easily rectified.
This disconnect can happen when the GiveSmart user who had originally generated the integration’s API key is deleted from GiveSmart, which causes an interruption in the API sync until a new key is generated and applied to Salesforce.
Troubleshooting Failed Transactions
If you notice a transaction has not synced after 4 days from being captured through GiveSmart, you may navigate to the On-Demand Sync tab and see if it has a Sync Status of "Failed".
Click on the MobileCause Transaction ID, which will bring you to the Transaction Detail page. Select the Related tab at the top.
The most recent Sync Log will be at the top. Click the Log ID to open up the detail.
Note the error message displayed under Error Log. If the Salesforce error is unclear, copy the content of the Error Log and provide this to Support when opening a case for next steps.
FAQs
What type of information is included in the sync?
Only monetary transactions made through GiveSmart Fundraise are synced, e.g., payments made through a GiveSmart Fundraise payment form via credit card, PayPal, or Google Pay.
Will non-payment data sync?
No - Information that is not associated with a monetary transaction is not eligible to be synced. This means that volunteer signups, free registrations/RSVPs, offline donations, etc. will not be synced.
Will recurring donations be included in the sync?
Yes – recurring donations and subsequent installments will always sync to Salesforce as individual opportunities. However, it is not possible to sync recurring installments to an existing Opportunity, nor is it possible to have these sync to Salesforce’s recurring donations object/scheduler.
You can view and manage your GiveSmart Fundraise recurring donations by heading to Existing Reporting > Recurring Donations at any time.
How does the integration handle Contact matching?
The contact matching is done solely by email address and will look at all 4 default email fields in Salesforce one by one: email, personal email, alternate email, work email. If no email match is found, a new Contact will be created. You are not able to define “and/or” logic or use fuzzy matching within the app at this time.
Will any data get overwritten?
In the Global Form Mapping template, if the "exclude on matching" box is checked next to any field mapping, this means that the integration will *not* update/overwrite this field when a contact match is found. This is recommended and checked by default for key contact fields such as First and Last Name.
How do I deactivate the sync?
If the sync needs to be paused for any reason, you can turn off the scheduled sync in Salesforce by heading to Settings > Setup > Search: scheduled jobs and delete the job titled MobileCause Integration. You can then restart the job at any time from the On-Demand Sync tab by selecting 'Schedule Daily Sync'.
Does the GiveSmart/MobileCause integration user used for the installation need to remain active in Salesforce?
So long as the daily sync was not activated by this user, it can be deactivated without interruption to the sync. If you need support with troubleshooting or adding field mappings in the future, we will kindly ask for the admin user to be reactivated.
What Salesforce objects does the integration map to?
The integration maps to the SDFC Opportunity and Contact objects. We can map to any fields on these two objects. If you are utilizing Salesforce’s NPSP (Nonprofit Success Pack), new Account and Payment objects will get created for new opportunities, depending on your NPSP Settings.
Why are my transactions not syncing?
- Once the daily sync is activated, the integration will only attempt to sync any new transactions that have reached a Billing Status of “settled” within the last 3 days. Since settlement is dependent on the card-issuing bank, transactions can often take 1-3 days to sync once they are first captured through your form.
In your GiveSmart Fundraise reporting, refer to the "Billing Status" reporting column for sync eligibility.
If you notice that a transaction has not synced after 3+ days or reflects a “Failed” status in the On-Demand Sync tab of the MobileCause Salesforce app, please submit a new support request.
Where can I find a report of all synced transactions?
In the Salesforce app head to the tab titled “MobileCause Transactions.” Here you can sort by “All” to return all transactions retrieved from GiveSmart Fundraise with their Sync Status, Date, Name, Opportunity, and other details.