Welcome to Encatch Docs
Data syncBetaConnectorsCRM

Salesforce

Create or update Salesforce records from Encatch survey responses - how to set up the integration user and External Client App in Salesforce

Overview

The Salesforce connector writes survey responses to Salesforce as records, for example Contacts, Leads, Accounts or a custom object. Each submitted response creates a record or updates the one it matches.

Encatch connects through an External Client App that you create in your own Salesforce org, running as an integration user you control. Encatch never signs in as a person: every record it writes shows the integration user as its creator, and you can switch the app off at any time.

What it getsA record created or updated from each response
EventsSurvey submitted, and Survey partially submitted when ticked
Anonymous respondentsNot sent: identified users only
Test connectionChecks the keys only: nothing is written in Salesforce
StatusAvailable

What You'll Need

Before you start, make sure you have:

  • A Salesforce admin — with Customize Application and Manage External Client Apps (or Modify All Data)
  • An edition with API access — Enterprise, Unlimited, Performance or Developer Edition, or Professional Edition with the API add-on
  • A spare integration user licence — Enterprise, Performance and Unlimited include 5 free Salesforce Integration licences (Developer Edition includes 1). Setup → Company Information → User Licenses shows how many are left
  • About 15 minutes

Step 1: Create the integration user

  1. In Setup, open Users → Users → New User.
  2. User License: Salesforce Integration. Choose it first: the Profile list then offers two profiles. Pick Minimum Access - API Only Integrations.
  3. First Name / Last Name: something you'll recognise, for example Encatch Integration.
  4. Email: an address you can reach. Salesforce sends notices there.
  5. Username: must look like an email address and be unique across all Salesforce orgs, for example encatch-integration@yourcompany.com. You'll need it in Step 4.
  6. Untick Generate new password and notify user immediately: this user never signs in.
  7. Click Save.

Step 2: Give it access to what Encatch writes

  1. In Setup, open Users → Permission Sets → New.
  2. Label: for example Encatch Data sync. The API Name fills itself in.
  3. License: Salesforce API Integration (in the list under Permission Set Licenses). Click Save.
  4. Open Object Settings → the object Encatch will write (for example Contacts) → Edit:
    • under Object Permissions, tick Read, Create and Edit;
    • under Field Permissions, tick Read Access and Edit Access for every field you'll map, including the field Encatch matches records on (for example Email);
    • click Save. Repeat for each object.
  5. Assign it: Manage Assignments → Add Assignment → the integration user.
  6. If your sharing settings for those objects are Private, make sure the integration user can see the records it should update, for example with a sharing rule.

Encatch only sees what this permission set allows. An object or field you leave out doesn't appear in Encatch's pickers at all.


Step 3: Create the External Client App

  1. In Setup, open Apps → External Client Apps → External Client App Manager → New External Client App.
  2. Fill in Basic Information:
    • External Client App Name: for example Encatch.
    • API Name fills itself in from the name. It may only contain letters, numbers and underscores: if your name has a hyphen or another symbol, change the API Name (for example Encatch_Data_sync), or the app won't save.
    • Contact Email: yours.
    • Distribution State: Local (the default).
  3. Open API (Enable OAuth Settings) and tick Enable OAuth. Then:
    • Callback URL: required by the form but not used. Enter https://localhost.
    • OAuth Scopes: select Manage user data via APIs (api) and move it to Selected OAuth Scopes. No other scope is needed.
    • Flow Enablement: tick Enable Client Credentials Flow and confirm.
  4. Click Create. The app opens on its Policies tab.

Step 4: Set the Run As user

The client credentials flow has a second switch, on the app's policies, where you choose which user Encatch acts as.

  1. On the app's Policies tab, click Edit and open OAuth Policies.
  2. Under OAuth Flows and External Client App Enhancements, tick Enable Client Credentials Flow.
  3. Run As (Username) appears: enter the integration user's username from Step 1.
  4. Click Save.

Step 5: Copy the credentials

  1. Open the app's Settings tab → OAuth Settings → Consumer Key and Secret. Salesforce emails you a verification code first.
  2. Copy the Consumer Key and the Consumer Secret.
  3. Find your My Domain address: Setup → My Domain. It looks like https://yourcompany.my.salesforce.com. A Developer Edition org ends in .develop.my.salesforce.com, a sandbox in .sandbox.my.salesforce.com. Use this address, not login.salesforce.com.

A new app can take a few minutes to work. If Encatch says the key is wrong right after you create the app, wait a few minutes and test again.


Step 6: Add the connection in Encatch

  1. In Encatch, open Data sync → Survey events and click Add connection.
  2. Choose Salesforce and enter a Name.
  3. Enter your My Domain address, Consumer Key and Consumer Secret.
  4. Click Load from Salesforce. Encatch signs in as the integration user and shows Connected to …, then reads the objects it can create and update and the fields of the object you choose. Nothing is changed.
  5. Fill in the record settings:
FieldWhat to enter
ObjectThe record type Encatch creates or updates, by its API name, for example Contact or Survey_Response__c.
Find the recordFind by a field, create if none (default), Update by the record ID held in a trait, or Always create a new record.
Field that finds the recordThe Salesforce field to match on, for example Email, and the Encatch value to compare it with.
Fallback fieldOptional. A second way to find the record, for example an External ID field holding the Encatch user ID.
Field mappingOne row per Salesforce field: the field, and the Encatch value written to it.

Values you can map: an answer to a question, the score (first NPS or rating answer), the survey name, the response ID, the submitted time, the response status, the user ID and any user trait.

  1. Press Test connection. It signs in as the Run As user and reads the fields of the object you chose.
  2. Pick the surveys, click Save, then press Start sending.

If you find records by email, add a fallback. With no value for either, nothing is written and the event shows as Skipped in Logs.


Check it in Salesforce

  • Records Encatch creates or updates show the integration user (for example Encatch Integration) as Created By and Last Modified By.
  • Logs in Encatch show what Salesforce answered for each response.

Turning it off or changing the secret

  • Stop Encatch at once: in External Client App Manager, open the app and click Disable, or deactivate the integration user.
  • New secret: generate a new Consumer Secret on the app's Settings tab, then paste it into Encatch with Replace.
  • Sandboxes: a Local External Client App is not copied when a sandbox is created or refreshed. Create the app again in the sandbox and connect it as a separate connection.

Good to know

  • API limits. Encatch's calls count against your org's daily API limit, shared with other integrations (Enterprise: 100,000 a day plus 1,000 per user licence; Developer Edition: 15,000). One response is usually one or two calls.
  • Rate limit. Salesforce limits API calls per day, not per minute: the connection's rate limit cannot protect the daily allowance.

Troubleshooting

What Encatch showsWhat it meansWhat to do
Salesforce doesn't recognise this consumer keyThe key is wrong, the app is brand new, or the address is login.salesforce.com instead of your My DomainCheck the My Domain address (Step 5), copy the key again, or wait a few minutes after creating the app
Salesforce refused the consumer secretThe secret is wrong or was regeneratedCopy it again from the app's Settings tab and paste it with Replace
Client credentials aren't set up for this appThe flow is off, or no Run As user is setStep 3 (Flow Enablement) and Step 4 (both the policy switch and Run As)
The integration user can't see objectThe permission set has no access to that objectStep 2: Object Settings → the object → Read, Create, Edit
Field isn't available to the integration userNo field access in the permission setStep 2: Field Permissions → Read and Edit on that field
Salesforce blocked the login from this addressLogin IP ranges on the integration user's profileOn the app's Policies tab → App Authorization, set IP Relaxation to Relax IP restrictions
Salesforce's daily API limit was reachedThe org's daily calls are used upEncatch retries later; check other integrations' use in Setup → System Overview

Was this page helpful?