In This Article:

    Syncing Supporters and Contacts

    In This Article:


      This information is useful if you are a data manager who needs to understand the processes the integration uses to sync Contact data to and from Salesforce and how to quickly find their information. This document...

      • Describes managing when and how the integration creates new Engage supporters or Salesforce contacts or matches with existing contacts.
      • Describes whether to override other Duplicate Rules in Salesforce.
      • Discusses processes for Salesforce admins to manage Salsa Engage New Supporter Queue entries, deletions, and contact merges.
      • Provides tips on how to locate synchronized records in Engage and Salesforce.

      Each time the integration syncs, the integration determines whether there are any potentially matching contacts before creating a possible duplicate. New Salsa Engage supporters are sent to Salesforce. However, instead of immediately creating a contact for each new supporter, the integration will first stage the record in a custom object in Salesforce called the Salsa Engage New Supporter QueueOnce there, the integration will use a special rule that’s installed in Salesforce’s built-in Duplicate Matching and Detection tools to compare the staged supporter with your existing contacts. The rule looks for an exact match on Last Name and Email as well as a 'fuzzy' match on First Name. Click here to see what we mean by 'fuzzy'. While the default matching rule is sufficient for most organizations, advanced users can add a custom matching rule that uses different logic instead. This is described in detail below.

      In Engage, you can opt for the integration to always create a new Contact or attempt to sync with an existing contact that matches with an existing Salesforce contact automatically, or the integration can always send those new supporters to the Salsa Engage New Supporter Queue to be resolved individually. This option is found under Handling New Supporters section in the Salesforce menu under the Settings tab.


      Creating New Contacts Automatically

      Click Queue All New Supporters in Salesforce and let me decide to queue all new supporters in the Salsa Engage New Supporter Queue for a Salesforce administrator to resolve. This includes new supporters that had no potential matches. While waiting for manual resolution, no activities, donations, or other records associated with that new supporter will be pushed to Salesforce. This ensures that the connected activity records are added to the correct contact in Salesforce once resolved.

      Click Automatically Create a New Contact or Attempt to Sync With Existing Contacts That Match to automatically create new supporters that have no potential matches as new contacts. We provide a few additional options when you select this option that will determine what happens if there are potential matches.

      Matching with Existing Contacts Automatically


      Set Auto-match new Engage Supporters with existing Salesforce Contacts to No to automatically create a new contact from new supporters without any potential matches. If any potential match is found, it will be queued in the Salsa Engage New Supporter Queue for a Salesforce administrator to resolve.

      Set Auto-match new Engage Supporters with existing Salesforce Contacts to Yes to allow the integration to look at the number of potentially matching contacts before deciding whether to auto-match.

      • If only one potentially matching contact exists, it will automatically connect to that contact.
      • If more than one potential match is found, a further setting decides whether the integration should automatically match with the oldest or the most recently modified contact. Or, you can choose Let me decide to leave it queued in the Salsa Engage New Supporter Queue for a Salesforce administrator to resolve.

      NOTE: Whenever auto-matching is enabled and the contact that it should match with has the Do Not Synchronize with Engage contact field checked, the integration will NOT auto-match in that case. Instead, it will remain queued in the Salsa Engage New Supporter Queue for a Salesforce administrator to resolve.

      Overriding other Duplicate Rules in Salesforce


      Overriding other Duplicate Rules in Salesforce may be necessary to create new contacts through the integration. The integration uses the API to manage the creation of new contacts. If, for example, your Salesforce account has a rule set to alert whenever a new contact matches an existing contact’s Last Name, it may prevent the integration from creating a new contact through the API.

      Setting this option to Yes allows the integration to override those rules and create contacts through the API without having to change your existing duplicate rules that alert in Salesforce. This includes overriding the Standard Contact Duplicate Rule, which comes activated by default in Salesforce accounts.

      NOTE: Any duplicate rules explicitly set to 'Block' the creation of duplicates in Salesforce cannot be overridden through the API and must be set to 'Allow'.

      Resolving Entries in the Salsa Engage New Supporter Queue

      Entries made in the Salsa Engage New Supporter Queue that have not been cleared automatically by the integration must be resolved by a Salesforce administrator. You can find the queue in Salesforce under the App Launcher while using the Lightning Interface or as a tab in the Classic Interface. Search for Salsa Engage New Supporter Queue.


      If there are any pending entries, they will be listed. You can click into an entry to see any potentially matching contacts. You can decide whether to create a new contact for this record or match with an existing contact by clicking the 'link' button.


      Once a decision is made, the full supporter data, donations, and other activity records tied to the pending new supporter will be sent to Salesforce and applied on the next sync.

      Adding a Custom Duplicate Rule and Matching Rule in Salesforce

      To add a custom rule...

      1. Go to Duplicate Rules in the Salesforce Setup menu. Click on the New Rule button and select Salsa Engage New Supporter Queue.
      2. In the resulting window, give your rule a name and description.
      3. Under Actions...
        • set the options for both Actions on Create and Actions on Edit to Allow. Note: if you set either option to Block, the sync will not be able to create new contacts.
        • Check Alert and uncheck Report.
      4. Under Matching Rules...
        • select Contacts for the object to compare to the Salsa Engage New Supporter Queue.
        • Either --Select a Matching Rule-- OR  --Create New Matching Rule-- option.
          If you select to create a new matching rule, you will be prompted to add a new matching rule. Click here to learn how to create Matching Rules. After creating your matching rule, you’ll return to the Duplicate Rule creation screen.
        • Set the mapping between the two objects you’re comparing by clicking on the Field Mapping link Mapping Not Selected.
        • Click Add Rule to create the new Duplicate Rule.
      5. Once the new Duplicate Rule is created, click Activate to activate the new rule.
      6. Deactivate the Salsa New Supporter Fuzzy Match rule added by the integration so that it doesn’t conflict with your new custom rule.

      What if a New Supporter Matches a Contact that’s Already Synced to Engage?

      Before matching a new supporter from Engage to an existing contact, the integration will check to see if the contact found by the matching rule already has been synced to Salsa (which is determined by the matching contact record having an Engage Supporter Id). If the matching contact is already synced to Engage, the new supporter will remain in the Salsa Engage New Supporter Queue.

      The queue entry will list the matching contact with options to either create a new contact or select a matching contact. However, instead of providing the option to “link” the new supporter with the existing contact, there will be an option to Merge.


      If you select the Merge option, on the next scheduled sync the pending new supporter in Engage will merge into the preexisting supporter record that’s already synced to the matching contact. None of the new supporter’s contact information is kept, however all activities that were associated with the new supporter are reassigned to the preexisting supporter and synced back to Salesforce. In addition, the contact will be added to any campaigns the duplicate supporter had been a part of as well as be made the Primary Contact on any Opportunities that get created from donations that are subsequently synced.

      If you want to retain any new supporter contact or address data, use the Create New Contact option instead. After the new contact has been created, merge the two matching contacts using Salesforce's merge tools. This will allow you to retain or reject some or all of the contact or address data stored in the new contact. Once merged, the resulting master contact in Salesforce will then be merged in Salsa as well.

      How the Integration Handles New Contacts in Salesforce

      Each time the integration syncs, the integration looks for any new contacts that have been created since the last time it ran. For these new contacts, the integration will check to see if any are eligible to sync before creating a matching Supporter in Engage.

      A new contact is eligible to sync if the Do Not Synchronize With Engage field is not checked.

      Eligible contacts will then be compared with the existing Supporters in Engage to check for duplicates on email address.

      • If the new contact’s primary email address is already in use in Engage and that Engage record is synced to a contact record, it does not create a duplicate Engage supporter. Only one record can exist in Salsa Engage with the same email address at a time. An error entry will be made in the Errors tab indicating which record was a duplicate.
      • If the new contact’s primary email address does exist in Engage but the Engage supporter has NOT synced with any record in Salesforce, the integration will place a new entry in the Salsa Engage New Supporter Queue in Salesforce. If a pending queue entry already exists, then the new contact will be added to the list of potential matches for a Salesforce administrator to resolve manually.

      For all remaining eligible new contacts, the integration creates new, matching supporter records and keep them in-sync moving forward.

      How the Integration Handles Updates to Synced Supporters and Contacts

      Updates made to synced supporters and contact records follow the Field Mapping rules set in the integration settings.  For each field, there are two rules that apply to an initial sync between a supporter and contact as well as a set that applies to ongoing updates. Each time the integration syncs, any updates that have been made in either system will be applied bidirectionally according to these rules.

      For example, if the First Name of a contact record in Salesforce is updated and the First Name field mapping is set to 'Always use Salesforce value, even if it is blank'. then when the integration syncs it will update Engage to match what’s in Salesforce. Conversely, if the field mapping was set to 'Use Latest', then any update on either system that was most recently committed is applied in both systems.

      Using the 'Create an Update Entry in Salesforce' Mapping Rule

      For any Standard Field, you can use Create an Update Entry in Salesforce as an ongoing rule to queue updates in Salesforce before they’re committed. This rule is designed to give you manual control over when an update from Engage is kept. It gives you the ability to keep contact information clean in Salesforce (as the database of record).

      When used, updates to the field will be stored in the Salsa Engage Update object in Salesforce. The update entry will contain all standard fields along with the update made to the field requiring review. Salsa Engage will revert to the Salesforce value for this field on sync and allow the Salesforce manager to decide what to do with the update at their convenience.

      In Salesforce, these Salsa Engage Update objects can be reviewed and then dismissed or used to update the contact.


      If the update is applied, the update will be applied to the contact record and then update Engage on sync.


      You can find a list of all pending Salsa Engage Updates under the App Launcher while using the Lightning Interface or as a tab in the Classic Interface. Search for Salsa Engage Update Queue.

      Email Subscription Management

      When you install the Salsa Engage integration app, the custom field Email Subscription Status is added to the Contact record. The integration uses this field to track the synced Engage supporter's subscription status. If a supporter changes their Engage subscription status from 'Subscribed' to 'Unsubscribed', the Email Subscription Status field in Salesforce will also update from 'Subscribed' to 'Unsubscribed' when the systems sync with each other.

      This field will also stay in sync with Salesforce’s standard field for tracking email subscriptions, called Email Opt Out. This standard field is a checkbox, designed to track who has opted out of receiving emails from your organization.

      If you change the Salesforce Email Opt Out field to be checked, the custom Email Subscription Status field will also update to 'Unsubscribed'. When the sync runs, the connected Engage record's Email Subscription Status changes to 'Unsubscribed'. Similarly, if a supporter in Engage changes their Email Subscription Status to 'Unsubscribed,' the sync changes the Salesforce Email Opt Out field to be checked.

      The Salesforce Email Subscription Status field will only update through a sync from Engage or by changing the standard Email Opt Out field checkbox. If you change the custom Email Subscription Status field in Salesforce, it will revert to whatever is set in the Email Opt Out field.

      Syncing Hard Bounces

      If an Engage email that is sent to a supporter hard bounces, the supporter's Engage Email Subscription Status is subsequently changed to 'Unsubscribed'. When that record syncs to Salesforce, the Salesforce contact Email Subscription Status field updates to 'Hard Bounced' and the Email Opt Out field becomes checked.

      Nonprofit Success Pack’s 'Do Not Contact' Option

      The Nonprofit Success Pack has a built-in option to mark a Contact as 'Do Not Contact'. Click here to learn more about that field. When you select Do Not Contact, Nonprofit Success Pack will automatically check the Email Opt Out field for that Contact. Since the integration uses the Email Opt Out field, the associated supporter record will also be unsubscribed as of the next sync.

      Tracking Deletions

      In the integration settings, you can optionally set the integration to delete the synced contact or supporter record if a deletion occurs in either system.


      Merging Contacts

      When a contact record is merged with one or more contacts in Salesforce, the integration automatically records these merges and replicates the results in Engage. This includes moving any donations, activity records, email records, etc., to the winning supporter record.

      Locating Synchronized Records In Engage

      Salesforce records that have been synced to Engage can be identified by the presence of a Salesforce ID in the supporter record. To identify records synchronized to Engage, create a Supporter Query.

      1. Click Supporters tab > Query tab.
      2. Click the Create New Query button. The Create a Query page will open.
      3. Set the first line of the query to 'Supporter Fields' 'Salesforce ID' 'Is Not Blank'.
      4. Choose the fields you want to see in your query results.
      5. Save the query.

      Locating Synchronized Records In Salesforce

      Records synchronized from Engage to Salesforce have a unique Engage Supporter ID in Salesforce. You can generate a report in Salesforce that will search on Engage Supporter IDs that are not blank, similar to queries created in Engage that search for supporters with Salesforce IDs that are not blank.


      Was this article helpful?
      0 out of 0 found this helpful
      Have more questions? Submit a request



      Article is closed for comments.