Salesforce¶

Syncing Users¶

If you enable the User sync from ActionKit to Salesforce, information about Users who are eligible for sync will transfer to Salesforce for any fields you specify in the User field mapping.

To be eligible, the User must have a value for their last name (this is a Salesforce requirement) and either meet the criteria in your Salesforce Sync Report (more on how to set that up below) or have met the criteria and been included in the sync previously.

Once a User is included in the sync, their Salesforce ID is recorded in ActionKit in the core_salesforceusermap table and displayed on the user record. Any updates to fields you’ve mapped will transfer from ActionKit to Salesforce for Users with a Salesforce ID, even if that user no longers meet the Salesforce Sync Report criteria. If you must disable updates for a specific ActionKit user who is already in the sync, contact support.

The ActionKit to Salesforce sync runs automatically, sending data for any newly eligible or previously included user whose record has changed in the previous 10 minutes.

For users currently in the sync, it's possible to trigger an immediate sync from their user profile. The Salesforce heading of the User Details section shows Salesforce mappings for the user and includes a link to Sync Now. Clicking that and confirming the popup will trigger an immediate sync to SalesForce.

If you enable the User sync from Salesforce to ActionKit, information about Contacts who are eligible will transfer to ActionKit for fields defined in the User field mapping. Salesforce Contacts will be subscribed to your default mailing list in ActionKit the first time they are included in the sync.

To be eligible for the sync, the Salesforce Contact must not be marked DNC or deceased, must have an email address and must have the "ActionKit Opt In" box checked on their Salesforce record. By checking this box, you are confirming that this person wants to receive emails from your organization. There is no way to add a Salesforce Contact to the sync without subscribing the corresponding User in ActionKit. Further subscription management must be done through ActionKit.

You cannot uncheck the "ActionKit Opt In". To unsubscribe a User, search for them on ActionKit's Users Tab. Click through to their User record and click "Unsubscribe".

Once the Salesforce ID has been saved in ActionKit, updates for any fields you include in the User field mapping will continue to sync to ActionKit, except for updates to contacts who are marked DNC or deceased. This is true even if the User has bounced or unsubscribed in ActionKit. This keeps address and donation data in sync in case the User becomes mailable in ActionKit again -- otherwise you would have to manually sync any changes made in the interim.

If a contact in the sync is subsequently marked DNC or deceased, then the corresponding User will be unsubscribed. Taking action in ActionKit will not clear a DNC flag in Salesforce. If an action does subscribe an User sync'd to a DNC contact, then the sync will soon unsubscribe the User again.

The Salesforce to ActionKit sync is triggered whenever the contact record is updated in Salesforce and happens in very close to real time.

The core_salesforceusermap table shows ActionKit users that have been mapped to Salesforce contacts and shows the originating system for new users or contacts. The users in this table may not match the users found by the sync report. Any users made eligible since the sync was last run won't be in the map yet and users who once met, but no longer meet the criteria of the sync report will be in the map.

User Field Mapping¶

You can select fields, match them to fields in the other system and set the direction of the data flow for each pair. Email address and last name are required and the mapping for those fields cannot be changed. We provide default mapping for other fields, which you can edit or delete. You can also add additional fields, including custom fields from either system.

Warning

Both ActionKit and Salesforce have restricted fields which cannot be overwritten and fields that require specific values or formatting. Because the fields are customizable on both ends, we can't account for all possible variations. You'll get an error and you won't be able to save if we can tell a mapping is bad, but it is still possible to select options that will break the sync. See User Field Mapping Considerations for details.

For each field you map you can select:

• Bi-directional the most recent value from either system is used
• ActionKit to Salesforce Only the value from ActionKit, even if it's blank, always overwrites the Salesforce value
• Salesforce to ActionKit Only the value from Salesforce, even if it's blank, always overwrites the ActionKit value

Our recommended ActionKit User Field Mapping looks like this:

To add additional mappings, under "Add New" select the category (user, custom or location) in the box on the left. Then select from the drop down to the right of this. The "user" options include fields from the core_user and core_phone tables, as well as list_membership. The latter is a derived field that provides a semicolon-separated list of the names of the mailing lists the user is subscribed to. This field can be mapped to a picklist in Salesforce to see all of a user's subscriptions in a convenient display.

Map ActionKit custom user fields by clicking "custom" and choosing from a list of all your ActionKit custom User fields. Select the corresponding Salesforce field. All of your custom Salesforce Contact object fields are available for mapping.

Similarly, you can add User fields from the core_location table by selecting "location". You then have options like us_district and can choose which Salesforce Contact field to map your User location data. These should be set to "ActionKit to Salesforce only".

User Field Mapping Considerations¶

The field type and the data in the field will determine which can be synced and in which direction. We've added validation that errors if the fields you select can't be written to:

Or, if the values in one system don't meet the requirements in the other:

However, it is still possible to end up with a bad mapping, which can break your sync. You can protect against one possible cause by ensuring that you don't include a field in the mapping and later change the data in the field so it's inconsistent with the requirements. Once a field is in your mapping, review any changes to the data type or values to make sure they work with the sync.

Notes on specific mapping options follow:

• Pay special attention if you add a new mapping using a newly created field. The validation checks for existing values that can't be written to the other system, which means that a new field, with no values, has nothing to validate. You can map a text field for favorite color in one system to a date field in the other and it won't fail when you create the mapping, but values will not transfer. This will not break the sync but you won't see the data you expect.
• Understand how custom field validation works in ActionKit. While you can define Field Types for custom fields, the data is not validated for all possible avenues of entry. For example, if you set a custom user field to type 'Date' in ActionKit, this stops you from entering non-date values on the user record in the admin. This does not stop a user from entering non-date values in the same field on an action page unless you've applied custom validation when creating the page. If the ActionKit field type is "list" or "list with other", a non-matching value from Salesforce will transfer. In the display on the user record in ActionKit, ‘no longer a valid option’ will be appended. Think about how you'll use the ActionKit field and what you can do to keep the data clean when you're mapping to a restricted field type. Mapping to text fields of unlimited size is always safe.
• Understand how field types work in Salesforce.
  • The sync cannot write to fields with the data type Lookup in Salesforce.
  • The sync can write to fields with the type picklist in Salesforce. For restricted picklists, ActionKit field values must exactly match the values defined in your Salesforce instance before adding the mapping.
  • The sync can write to fields with the type checkbox in Salesforce. A checkbox field in Salesforce transfers a "1" if checked to any field it's mapped to in ActionKit. Checkbox and boolean fields in ActionKit can both be mapped to checkbox fields in Salesforce.
  • Only map ActionKit fields that can have variable length to unlimited text fields in Salesforce. If the Salesforce field cannot hold the ActionKit-supplied value (for example, if ActionKit supplies 75 characters and the Salesforce can only hold 50 characters) from an action the sync will fail. It can only be fixed by removing the mapping.
• If the State and Country Picklists feature is enabled in Salesforce, ActionKit state fields should map to mailing state code fields in Salesforce.
• The location fields in ActionKit and the lat/long fields in Salesforce are calculated. That means they cannot be overwritten by the other system.
• Plus4 is automatically appended to zip when it's transferred to Salesforce if zip is included in your mapping.

See Limitations and Workarounds for additional details on mapping options.

User Sync Reports¶

You set the criteria in ActionKit for which Users are eligible to be synced to Salesforce.

Reports tagged “salesforce_sync” are used to define the criteria. From the ActionKit Salesforce Integration Settings screen, click on "User Sync Reports" to view a list of reports with this tag.

ActionKit ships with one built-in report with this tag. This report returns only subscribed users.

The suggested Salesforce sync report is: SELECT id FROM core_user WHERE subscription_status='subscribed'

We automatically exclude users with no last name from the sync because Salesforce does not allow contacts with no last name.

Remember, your ActionKit report(s) sets the criteria for who is added to the sync. Once a User is included in the sync they cannot be removed, even if they no longer meet the criteria.

Syncing One-Time Donations (Orders)¶

If you’ve enabled the donation sync in either direction, information about eligible individual gifts will transfer as you specify. Only successful, one-time donations that meet the criteria in your Donation Sync Report (described below) are included. If you are using our default Donation Sync Report, when a user or contact is initially added to the sync, historical donation records will sync for included users. Remember, only donations for users/contacts who are in the map are synced.

We designate the contact who maps to the ActionKit donor as the opportunity's primary contact so that donor gets the hard credit regardless of their role in the household in Salesforce.

Full refunds in either system will sync to the other.

Partial refunds in ActionKit will sync to Salesforce by creating a written-off (negative) payment in the amount of the refund and updating the Opportunity amount.

You must prompt refunds in the system where the donation originated.

Syncing Recurring Donations (Orders)¶

If you’ve enabled the recurring sync in either direction, information about eligible recurring commitments and payments toward that commitment will transfer as you specify. Eligibility is determined by the Donation Sync Report mentioned for one-time donations and the default report includes all recurring donations.

Recurring Donations are a custom object in the NPSP application, not a built-in Salesforce data object.

When you add a new recurring donation in the Salesforce, an opportunity will be created along with forecast payments (child records of Opportunities).

Note

Forecast payments will be created for the next 12 months by default. You can set the number of forecast payments in the Recurring Donations section of NPSP settings. While the value can be set to 0, a NPSP bug does cause the occasional creation of unexpected pledges.

By default, the Stage for each forecast payment is set to Pledged. As payments are processed, you change the status on the payment to Closed Won (or whatever status indicates a successful donation in your Salesforce instance).

If you’ve enabled the direction of the sync from Salesforce to ActionKit (or set it to bi-directional), we create a new recurring order in ActionKit corresponding to the recurring opportunity from Salesforce. Then when payments on the opportunities go from Pledged to Closed Won we add a row to core_transaction in ActionKit, associated with the ActionKit order id.

If you’ve enabled the direction of the sync from ActionKit to Salesforce (or set it to bi-directional), a new recurring opportunity is created in Salesforce when a recurring order is added to ActionKit. Then Salesforce creates the related payments with the Stage set to Pledged just as if the donation was added directly in Salesforce. As payments are made in ActionKit, the stage of the corresponding payment in Salesforce is changed to your successful payment stage, usually Closed Won.

When sync'ing an existing recurring donation to Salesforce for the first time, NPSP creates pledges for any past periods where no payment was made. By default, we regularly check for and change past pledges to future pledges. Pledges are not a requirement for the ActionKit sync, and may be deleted if desired.

To create a new recurring opportunity in Salesforce, you need to make sure it is set up correctly. We recommend following NPSP settings for recurring donations.

Note

If you need to change the amount or duration of an existing recurring donation in Salesforce, be sure to follow NPSP instructions.

Donation Sync Reports¶

Unless you have a specific category of donations you don't want sent to Salesforce, you shouldn't edit the Donation Sync Report. The default report includes all one-time donations and recurring payments so these will transfer to Salesforce for any user in the sync.

If you do want to limit the donations to be synced, you can edit the existing report tagged salesforce_donation_sync, or add your own. If you have already imported some ActionKit donations into Salesforce without recording the transaction_id (for one time) or the recurring_id (for recurring) in Salesforce, you may want to exclude the donations you've imported from the sync. ActionKit will create duplicate donations unless the unique identifiers are already in Salesforce.

The reports must select two columns: order_id and transaction_id. Order_id is always required. A transaction_id is optional for onetime and recurring donations, and is required for recurring payments. Remember, the Donation Sync Report only applies to donations from users who are in the sync.

Mapping Edits¶

When you change your field mappings for users, orders or recurring orders, the changes do not apply retroactively. For example, if you add a custom userfield to your mapping, users who already have a value for that field in ActionKit will not have the value transferred automatically. Only future entries in the field will transfer. You can force the sync by importing users whose records have changed -- a new action prompts ActionKit to update all mapped fields. Make sure to test your new mapping when you apply it; invalid mapping can break the sync. See User Field Mapping Considerations for details.

API Calls¶

The sync tracks Salesforce API calls used and shuts off once we hit a designated percentage (defaults to 40%). If you'd like to change the limit, let us know through support.

..You can configure this limit on the Salesforce Integration Settings page. Once your Salesforce org is below its API call limit, it will start again.You can also configure email notifications for when the sync pauses after hitting the API call limit on the Salesforce Integration Settings page.

You can use the table below to estimate API calls for given actions. Actual usage will fall between the bulk and single call counts because the sync will run with whatever is available every 10 minutes instead of waiting for a minimum number.

Clean-Up Processes¶

Missed Information (hourly): The sync will occasionally miss information due to Salesforce limits or brief connectivity outages between Salesforce and ActionKit. This hourly cleaner checks for missed information and ensures data integrity.

Recurring Donation Naming: This cleaner addresses common naming issues for pledged opportunities in Salesforce that are part of recurring donations.

For unsupported mapping choices¶

If you need to set a lookup field in SF based on a field value in ActionKit, or you don't want to setup a mapping using a field that's values are likely to change over time, the following option can be used to set the field value in Salesforce.

Note

Process Builder processes may cause errors if not created correctly. Talk with your Salesforce consultant, learn about process builder in Salesforce Trailhead, or both, before continuing.

First, create a text field to hold the ActionKit-supplied value. This text field will be used behind the scenes; once you're done testing, you'll want to hide it from page layouts. The text field should be at least 256 characters long. (Going over the character limit will cause the sync to fail.)

For the purposes of this example, we'll use a picklist mapping and assume there's already an entity picklist field on your Salesforce opportunity object to hold the C3/C4 designation for the donation. Create a text field called ActionKit_entity that ActionKit can write to.

• Go to process builder and create a new process on the opportunity object
• For The process starts when, select A record changes and save the process.
• Click + Add Object and select Opportunity. The process should start when the opportunity is created because you want the update to run when an ActionKit field is filled in.
• Click + Add Criteria. Set the filter conditions to ActionKit_entity is not blank.
• Click + Add Action. Use the action type Update Records, and select the opportunity. Add the criteria for the action ActionKit_entity equals c3. Set new field value entity to c3.
• Repeat adding actions to the original criteria node for each text value/picklist value pair.
• Save the process and activate it.
• Test the process.

To make changes to the process, clone it and save as a new version of the process.

Capture an ActionKit Custom Page Field in a Donation¶

ActionKit's custom page fields don't map directly to Salesforce. You can, however, pass the custom page field through a hidden custom action field and then map that custom action field to Salesforce. In effect, you're copying the custom page field into a custom action field each time an action happens on the page.

First, set up the custom page field in ActionKit and the corresponding field in Salesforce. The Salesforce field should be on the opportunity object and should be the type text.

In ActionKit, you'll go to the templateset editor for your primary templateset and insert something like this in the donate.html template inside the <form> tags. When your page field exists, you're filling in the custom page field as the value of a hidden action field. Repeat this step for each templateset that has donation pages.

{% if page.custom_fields.your_field %}
    <input type="hidden" name="action_your_field" value="{{ page.custom_fields.your_field }}">
{% endif %}

At this point, make a test donation to make sure the page field's value is ending up in a custom action field for the donation. The test also pulls the custom action field name into the available action fields for mapping. It won't sync to Salesforce yet.

Finally, you'll add it to your mapping under order mapping and/or recurring mapping, as appropriate. Map the custom action field to the Salesforce field you set up to hold its value. Run another test to make sure it's sending the data from ActionKit to Salesforce.

Using Validation Rules¶

Validation rules may prevent ActionKit from updating the fields or objects they apply to. If you have validation rules in place, you may need to use NPSP settings or ActionKit custom action fields to bring in the needed information before it's validated by the rule.

Recurring donations can be particularly tricky because NPSP creates the child opportunities based on the recurring donation's values. The recurring donation therefore needs to pass any required values into its child opportunity.

• Go to NPSP Settings > Recurring Donations > Recurring Donation Custom Field Mapping
• Add a new custom field mapping
• Map the recurring donation field to the opportunity field

Duplicate Matching¶

To ensure you're not creating duplicate Contacts and Accounts in Salesforce you may want to fine tune your matching rules (what criteria defines a match) and your duplicate rules (what to do with a match when it's found).

We recommend making sure that your matching rules contain a match for email addresses and turning off the duplicate rules for Contacts and Accounts. Duplicate rules provide the option to allow or stop Salesforce from creating a new record for the same person. Duplicate rules can also be set to alert and/or report any suspected duplicates.

Note

Duplicate rules set to Alert will temporarily break the sync if Salesforce finds a duplicate.

You have several options for managing duplicates that can be used individually or together:

• Modify your duplicate rules to "Report" checked, but "Alert" unchecked.
• Set duplicate rules to run for all Salesforce users except the ActionKit API User.
• Merge duplicates directly through the NPSP de-duplication feature, using the record with the ActionKit ID as the master.

Never Subscribed Donors¶

If you have an opt-in checkbox on your donation page, including the built-in one we provide for Canadian users, you may have donors who are never subscribed. You may want to include a salesforce_sync report for never subscribed donors and include subscription status in your mapping in order to feed all donors into Salesforce. More narrowly, you could include Canadian donors with never subscribed status in your sync.

Context¶

The context passed to a sync template always includes:

• action: create or update. The recurring payment template also supports a pledge_conversion action, when the sync converts a pledged recurring payment in Salesforce to a successful payment.

• field_mappings: a list, comprised of dictionaries with the keys mapping and value.

  • mapping is an instance of either SalesForceFieldMap, SalesForceOrderFieldMap, or SalesForceRecurringOrderFieldMap.
  • value: Renders as a a JSON encoded string value.

Additional context may be available depending on the action and template:

• salesforce_id: for updates, the Id of the object to update

• order object: for opportunity, recurring donation, and recurring payment templates.

• user object: available in user templates

• payment: transaction object, available in the recurring payment template.

  Warning

  While customizing templates, be careful not to remove the From ActionKit field. This is used to prevent updates from echoing between ActionKit and Salesforce.

Safety¶

Data from the field_mappings object is already encoded for use in JSON.

JSON encoding is NOT applied to data pulled from other objects, such as user, order, etc. Any data from these objects that could include user-provided data, such as name or custom fields, must be quoted and escaped with |escapejs e.g. "{{ user.source|escapejs }}" or "{{user.custom_fields.favorite_color|escapejs}}"

Testing Template Customizations¶

To test template changes, we suggest calling the sync_user REST API endpoint.

Call the API endpoint with use_bulk=1 to initiate a sync of the user to Salesforce using a Bulk Data Load Job. The API response will report any errors assembling and delivering the payload to Salesforce.

Currently this endpoint only sync's user data. In the future we plan to expand this to orders and payments, and also enable use with users not already in the sync.

The "Sync User" link on user profiles will also trigger a sync using the Bulk Data Load Job, but unlike the API call it doesn't provide error details.

Customization Examples¶

Some examples include:

• Sync user source to a Salesforce contact field:

"actionkit_user_source__c": "{{user.source|escapejs}}",

• Special handling of a troublesome field:

{% if user.custom_fields.favorite_color in 'green,orange,blue' %}
  "favorite_color_picklist__c": "{{user.custom_fields.favorite_color|escapejs}}"
{% endif %}

• Sync to a particular Salesforce Contact

{% if user.custom_fields.salesforce_contact_override %}
  "Id": "{{user.custom_fields.salesforce_contact_override|escapejs}}"
{% else %}
  "Id": "{{contact_id}}"
{% endif %}

In the future it will also be possible to customize handling of users that don't have a last name. Currently there's a hard-coded suppression of users without a last name. We plan to make the handling configurable.

ActionKit User Not Syncing to Salesforce¶

• Confirm the user has a last name in ActionKit. This is a Salesforce requirement for Contacts.
• Confirm that the user matches a User Sync Report in ActionKit.
• Check the user profile page in ActionKit for alerts on sync failures for this user. Note that we always wait 3 hours before trying to sync a user again after a failure.

ActionKit Donation Not Syncing to Salesforce¶

• Confirm the ActionKit user associated with the donation has synced to Salesforce.
• Confirm that the donation matches a Donation Sync Report in ActionKit.

For donations that have already in the sync with Salesforce, note that we'll only update donation amount and status.

Salesforce Contact Not Syncing to ActionKit¶

• Confirm that the contact's ActionKit Opt-In field is checked.
• Confirm that staff working in Salesforce have been assigned a permission set of either ActionKit Standard User or ActionKit Opt-In User.

Salesforce Opportunity or Recurring Donation Not Syncing to ActionKit¶

• Confirm that the opportunity's contact has been sync'd to ActionKit.

Advanced Troubleshooting - Sync Data and Salesforce Errors¶

Once these basics have been checked, the next most common reason for data missing from Salesforce is a field incompatibility. For example, data in an ActionKit that is too long for the mapped Salesforce field.

For data types other than recurring donations, you can see the raw sync data sent from ActionKit as well as Salesforce's response in Salesforce's Bulk Data Load Jobs. This is part of Salesforce's Setup UI.

Bulk Data Load Jobs are organized by data type and operation. For any given run of the ActionKit to Salesforce sync, there’ll usually be query/insert/update jobs for contacts, opportunities, and recurring donations. Update and insert jobs have batches, and each batch has one or more rows corresponding to object from ActionKit. When individual rows fail, Salesforce often reports a useful.

When an entire job fails the errors are less helpful. ActionKit Support may be able to provide more details of why a particular job died.