Skip to main content

Salesforce

Connect your Gravity Rail workspace to a Salesforce org so your CRM and your Workflows work from the same data. Link each Member to a Salesforce Contact or Lead, push Member updates to Salesforce, pull Salesforce changes back into Gravity Rail, send Data Type records to Salesforce records, and log Chat activity as completed Salesforce Tasks. Agents in the workspace can also query and update Salesforce records during a Chat.

This guide walks through the setup a builder does once per workspace. For the full settings reference, see the Salesforce settings reference.

Before You Start​

You need two things:

  1. A Salesforce admin. They must be able to approve the connection. If you use your own app, they also create a Connected App or External Client App in your Salesforce org.
  2. A Salesforce org with API access. Enterprise, Unlimited and Developer Edition orgs all work. A free Developer Edition org is a good place to try the setup first.

Your workspace needs the apps:read and apps:write scopes, like the rest of App Connections. Salesforce ships to every workspace; no feature flag turns it on.

One Salesforce org connects to one workspace. To connect a second org, use a second workspace.

Connect Salesforce​

Open Setup to choose the connection path. When the Gravity Rail app is offered, you can connect without creating an app. The steps below cover using your own Salesforce app; the page guides you through its credentials and authorization.

Step 1: Install Salesforce​

  1. Open App Connections and select the Directory tab.
  2. Find Salesforce, click Add, then confirm Add.

The Salesforce connection page opens with a Setup in progress badge. Open Setup for the connection guide. If the Gravity Rail app is offered, you can connect there without creating your own app; see the Salesforce settings reference. For your own app, choose Advanced: use your own Salesforce app. The guide's first step shows the OAuth callback URL and OAuth scopes for your workspace before you enter credentials.

Step 2: Create the app in Salesforce​

In Salesforce Setup, open App Manager and create either app type. Both give you the same two values.

App typeWhen to use it
External Client AppNewer orgs (Spring '24 or later). Not available to users until you grant access under the app's Policies.
Connected AppWorks on every edition. Available to all org users by default.

On the app:

  1. Turn on OAuth and paste the callback URL from the guide's first step. It must match exactly.
  2. Add the four OAuth scopes the guide lists: api, refresh_token, offline_access, openid, and id, profile, email, address, phone.
  3. Save, then copy the Consumer Key (your Client ID) and the Consumer Secret (your Client Secret).

New apps can take 2-10 minutes to become active in Salesforce.

Choose a connection type​

The credentials dialog asks for a Connection type. Both types use the same Client ID and Client Secret.

Server-to-server (recommended)User authorization
How it signs inGravity Rail gets a token directly from the stored credentials (OAuth Client Credentials Flow)A Salesforce user signs in and clicks Allow
Re-authorizationNever neededNeeded when Salesforce expires or revokes the user's refresh token
Extra Salesforce setupTurn on the Client Credentials Flow and set a Run As userNone
Instance URLYour org's My Domain URL, for example https://yourorg.my.salesforce.comAny login URL, for example https://login.salesforce.com

Use Server-to-server unless your Salesforce admin cannot turn on the Client Credentials Flow. To set it up:

  • Connected App -- check Enable Client Credentials Flow in the OAuth settings. Then, under Manage > Edit Policies, set the Run As user.
  • External Client App -- turn on Enable Client Credentials Flow in both places: on the Settings tab, and under Policies > OAuth Policies. The Run As field appears under the Policies checkbox.

All API calls run as the Run As user, so pick an API-enabled user who can read and write Contacts, Leads and Tasks. The Run As field takes the Salesforce username, which is often different from the user's email. Copy it from Setup > Users.

Step 3: Enter your credentials​

  1. In the guide's second step, click Enter credentials.
  2. Choose the Connection type.
  3. Enter the Client ID, the Client Secret and the Instance URL.
  4. Click Create.
Org typeInstance URL
Production (user authorization)https://login.salesforce.com
Sandbox (user authorization)https://test.salesforce.com
Any org (server-to-server)Your My Domain URL from Salesforce Setup > My Domain

With Server-to-server, Gravity Rail checks the connection when you click Create. If the app is set up correctly, the badge changes to Connected and you are done.

Step 4: Authorize (user authorization only)​

  1. In the guide's third step, click Connect with Salesforce.
  2. Sign in to Salesforce with a user who has API access, and click Allow.
  3. The window closes and the badge changes to Connected.

Connection states​

BadgeMeaning
Setup in progressInstalled. No credentials yet.
Awaiting authorizationCredentials saved. The Salesforce sign-in is not complete.
ConnectedThe connection works.
Reconnect requiredSalesforce refused the stored credentials. Sync stops until you reconnect. Sync history stays visible.
ErrorSomething else failed. See Troubleshooting.

After Disconnect, past runs remain read-only on Sync (also reached through Last synced, when present), and sync controls stay unavailable until you reconnect.

A Member must be linked to a Salesforce Contact or Lead before most features can use that record. The link stores the 18-character Salesforce record ID as the Member's Connection ID (salesforce:id).

Open the Members tab on the Salesforce connection page. Use Link Members to start linking or review matches:

ActionWhat it does
Link MembersOpens a dialog. The primary action runs in the background, matches unlinked Members by saved Salesforce ID, email or phone, and syncs unique matches. Ambiguous or missing matches are skipped.
Review matches, inside Link MembersClick Find matches to search Contacts and Leads by email or phone for up to 50 unlinked Members. Choose each record to link. Manual linking can restore a link that you previously removed.
Sync linked MembersFetches every linked Member's Salesforce record again and applies your inbound rules. Use it after you link Members to records that already exist in Salesforce.
Import MembersBrings in Salesforce records you choose as new or linked Members. See Import Members below.
UnlinkRemoves the link. Salesforce data does not change. Gravity Rail also stops sync from linking that Member again automatically. Link the Member again to undo this.

Import Members​

Click Import Members on the Members tab, then New import. You need workspace admin access; without it the button does not appear. Under Who to import, choose one way to select people:

SelectionWhat you choose
A Salesforce list viewOne of your org's list views. Search for it by name. A list view re-runs its filters, so it is marked Dynamic: each run imports the records in it at that moment.
Salesforce records matching filtersOne or more filters on fields of the object the connection syncs, such as Contact. Each filter has a field, a condition and a value.
A CSV file of idsA CSV file (5 MB at most) with a header row. Choose the column that holds the Salesforce record ID.
  1. Click Preview. Gravity Rail asks Salesforce who matches and shows the count and the first rows. A preview never creates or changes a Member.
  2. Enter an Import name, choose the Member role for the people you import, then click Save import. A role other than the workspace's safe default also requires role administration (member_roles:admin); see Roles and Permissions. These fields appear after a preview, and you must preview a selection before you can save it.
  3. Click Run on the saved import. The import runs in the background and links each record to an existing Member when one matches, or creates a Member.

Saved imports keeps each selection so you can run it again later. Each row shows its progress: imported, skipped and failed records. Run again runs the same selection again. Recent runs lists each run and its outcome. Deleting a saved import removes only the selection. The Members it imported, and their links, stay.

Why "sync now" matters. The scheduled inbound poll only reads Salesforce records that changed since the last poll. A record that has not changed in Salesforce will not arrive by itself after you link it. The Sync linked Members action fetches linked records directly. It requires app write access. With that access, manual review also offers Link and sync now; otherwise it offers Link without a sync.

Configure Member Sync​

Open the Settings tab. It holds your sync configuration as one form; click Save Sync Settings after you make changes. Sync holds the run action and the run history. If a save shows Sync settings were not saved, see When a Save Is Refused.

Salesforce settings​

SettingWhat it does
Target ObjectThe one Salesforce object Members link to and write to. The default is Contact. It must match the type of record your linked Members point at, or every write fails.
Upsert FieldThe field outbound sync uses to find an existing record before it creates a new one. The default is Email. Appears once member outbound sync is on.
Inbound Poll Interval (minutes)How often Gravity Rail checks Salesforce for changes. The default is 15. Values are kept between 15 and 1,440.

Direction, matching and conflicts​

The member sync settings control the flow of data:

  • Outbound -- push Member data from Gravity Rail to Salesforce.
  • Inbound -- pull Salesforce changes into Gravity Rail.
  • Match Strategy -- how sync finds the Salesforce record for a Member: Match by Email, Match by Phone or Linked ID Only.
  • Conflict policy -- what Member inbound rules do when a Gravity Rail field already has a value:
Conflict policyInbound behavior
Remote winsReplaces the Gravity Rail value with the Salesforce value. This is the default.
Keep localWrites only where no value is set. An empty Salesforce value still clears a synced field; Member properties keep their own handling of empty values.

The policy covers Member inbound rules only. Outbound writes and related objects are not affected: related-object values always replace the Gravity Rail value.

Start with Outbound only. Check the sync history after your first run, then turn on Inbound.

Sync rules​

A sync rule is a named group of field mappings, with outbound and inbound operations. A new member sync starts with three rules:

RuleOutbound (Gravity Rail to Salesforce)Inbound (Salesforce to Gravity Rail)
NameSplits the Member's name into FirstName and LastNameJoins FirstName and LastName into the Member's name
EmailCopies the Member's emailCopies the record's email
PhoneCopies the Member's phoneCopies the record's phone

The rule editor, the source dropdowns, transform presets and custom CEL expressions work the same way as for HubSpot. See HubSpot Sync for a full walkthrough, and the CEL expressions guide for functions.

An inbound rule can also honor Salesforce opt-outs. Under Notification opt-outs, choose a channel such as Opt out of calls when…, and write the condition that is true when the record opted out, for example source.DoNotCall or source.HasOptedOutOfEmail. On the next inbound sync, that channel is turned off for each Member whose condition is true, and Gravity Rail stops sending on it. Sync is opt-out only: clearing the checkbox in Salesforce does not turn the channel back on. To opt a Member back in, change their notification settings in Gravity Rail. Opt-outs belong to Member rules; related-object rules do not offer them. See HubSpot Sync for the full walkthrough.

An inbound rule that targets a Member field stores the value as a Synced field. Synced fields live on the Salesforce connection's Synced fields Data Type, one record per Member, and appear on the Member's Data tab under that Data Type. For example, an inbound rule from source.MailingCity to the key salesforce:MailingCity shows a "Mailing city" field on each linked Member. You can rename a Synced field on the Data Type. The key stays the same. See The Data Tab.

Filters​

Each direction can have an optional CEL filter. A Member or record that does not pass the filter is skipped.

FilterDirectionWhat it does
source.email != ''OutboundSends only Members with an email
source.MailingState != ''InboundReads only records with a mailing state

Inbound filters see the Salesforce record's fields, not Member data.

Sometimes the field you need lives on a different Salesforce object than the Member's Contact -- for example, a value on a custom object that points at the Contact or its Account. Once Inbound is on, the Related Objects section lets you read fields from that second object onto the same Member.

  1. Click Add related object and choose the Salesforce Object.
  2. Choose the Lookup Field -- the column on that object that points at the Member's record.
  3. Under Match records to members by, choose The record members are linked to (the lookup holds the Contact's ID) or A member field (the lookup holds another ID, such as an Account ID, that an inbound member rule already stores).
  4. Under Field Mapping, add inbound operations. A related-object operation can write a Member property (Core Properties), a Member field or a label (Labels). It cannot write Data Type fields or notification opt-outs, and Connection IDs are listed read only.

Related objects are read-only. Nothing is written back, and their values always replace the Gravity Rail value, whatever the Conflict Policy says.

Send Data Type Records to Salesforce​

The Data Type records section sends each Data Type record to its own Salesforce record -- for example a Lead, a Case or a custom object. The first sync creates the Salesforce record. Every later sync updates that same record.

  1. In Data Type records, click Add Data Type.
  2. Choose the Data Type and the Salesforce object. Each Data Type can have one mapping.
  3. Under Field mapping, add an operation for each Salesforce field. Each operation reads a field from the Data Type or from the Member who owns the record (for example member.phone).
  4. Click Save Sync Settings.

Turn Enabled off to keep a mapping but stop sending records.

Advanced has five optional settings:

SettingWhat it does
Only sync whenA CEL expression. A record is sent only when it is true, for example source.status == 'approved'.
Write record ID toAfter a successful sync, writes the Salesforce record ID to the Data Type record: External ID (the record's external-id column, shown in the Data Type records table) or a text field of the Data Type. Leave it on None to write nothing.
External ID fieldPrevents duplicate Salesforce records. Create a custom Text field (length 36 or more) on the object, and select External ID and Unique. Do not map it in a rule; sync fills it.
Member lookup fieldLinks the Salesforce record to the owner Member's linked Contact or Lead. For a Case, this is usually Contact ID.
Record type IDThe Salesforce record type for new records.

Things to know:

  • Data Type record sync is outbound only. Changes in Salesforce do not come back. The one thing written back is the Salesforce record ID, and only when Write record ID to is set. A text field target replaces a different value; an External ID that already holds a different value is never overwritten. A Data Type that holds a reference field cannot use a text field as the target: Write record ID to offers External ID only, and Data Type record sync refuses such a Data Type before it creates a Salesforce record, so no ID is written back today.
  • A row that still reads Synced can carry a note when the record ID was not written back, while the Salesforce record itself succeeded. The note names the reason: external_id_present, external_id_conflict, write_back_target_unavailable, or write_back_failed.
  • A Member Fields Data Type keeps one record per Member, so it updates the same Salesforce record each time it changes. For a new Salesforce record each time, the Data Type must store a new record each time, as a Member Table does.
  • Records from test runs are not synced.
  • Sync Now sends every existing record of each mapped Data Type. The first run after you add a mapping creates a Salesforce record for each one.

Log Chat Activity as Salesforce Tasks​

In the Settings form, you can log Chat activity as completed Salesforce Tasks on the Member's linked Contact or Lead. Turn on each kind you want. Each kind writes its own Task:

KindCreates
MessageOne Task for each message
Conversation summaryOne Task for each Chat after its summary is generated. It is updated in place when the summary is regenerated. Call details are added when the Chat had a call.
Chat startedOne Task as soon as a Chat exists
Call startedOne Task when a call starts
Call endedOne Task when a call ends, with disposition and duration

For each kind you can set a Subject Template, a Body Template and a Delay (seconds), and filter by Allowed workflows, Channels, Direction (Message only) and Exclude test chats (on by default). For Conversation summary, Create follow-up Task on escalation adds an open follow-up Task when a call was handed off or forwarded to a person.

Templates can use variables such as {{ chat.url }}, {{ chat.title }}, {{ chat.summary }} and {{ member.name }}. Repeats never duplicate a Task. Members without a linked Salesforce record are skipped.

Message content is patient data. The default message template does not include message.content. Add it only if your organization has confirmed that its Salesforce agreements cover that content. Your organization holds its own agreement with Salesforce.

See Where Salesforce Keeps Its Data​

The read-only Data tab shows how the connection recognizes a Member, which Data Types it keeps data in, and where every mapped field lives. The Data Type that holds your Synced fields is listed under Datasets. Field map groups rows into Member rules, Related object rules and Data Type record mappings. For what each dataset state and Field map column means, see Seeing Where a Connection Keeps Its Data.

Run a Sync and Read Sync History​

When outbound sync is on, Gravity Rail sends a Member's changes automatically when the Member is updated. Inbound sync runs on the poll interval. To run a full sync yourself, click Sync Now at the top of the Sync tab. Progress streams live while it runs.

To check one Member before you run a full sync, use Preview one Member's write on the Sync tab: choose a Member and click Preview write. It shows the Salesforce record the write would reach and every field value, and sends nothing. It is hidden while the connection needs reconnecting or is disconnected. See Write Preview for One Member.

The sync history at the bottom of the tab lists past runs. Each Member row shows the result for each direction: Synced, Skipped or Failed. A failed row names the reason. When Salesforce refused a write, the reason includes Salesforce's own error code, for example:

Salesforce error codeWhat it meansFix
DUPLICATES_DETECTEDA Salesforce duplicate rule blocked a new recordLink the Member to the existing record on the Members tab, or change the duplicate rule
REQUIRED_FIELD_MISSINGYour mapping does not fill a required Salesforce fieldAdd an outbound operation for that field
FIELD_CUSTOM_VALIDATION_EXCEPTIONA Salesforce validation rule refused a valueCheck the validation rule on the object
INSUFFICIENT_ACCESS_ON_CROSS_REFERENCE_ENTITYThe connected user, or the Run As user, cannot write to the objectGive that user create and edit access

To see every Member record that is failing now, grouped by cause, open Sync issues on the Overview tab (select the Errored count). Each cause shows the same explanation, how many records it affects and what to do. Show records lists the Members behind it, if you can see Members.

Below the runs, the history also lists the automatic actions the connection manages, such as Data Type record sends and Task logging, with any errors.

Agent Tools​

While the connection is Connected, Agents in the workspace can use six Salesforce tools during a Chat:

ToolWhat it does
salesforce_queryRuns a SOQL query, up to 200 rows
salesforce_searchSearches Contacts, Leads, Accounts and Opportunities
salesforce_get_recordGets one record by object type and ID
salesforce_create_recordCreates a record
salesforce_update_recordUpdates fields on a record
salesforce_describe_objectLists an object's fields and picklist values

Tell the Agent about your data model in its instructions -- for example, which objects matter and which fields to check. A Member's salesforce:id Connection ID gives the Agent the right record to look up.

Troubleshooting​

"Salesforce rejected the client-credentials grant"​

The Client Credentials Flow is not fully on. On an External Client App, check that both Enable Client Credentials Flow checkboxes are on and that a Run As user is set under Policies. Wait a few minutes for Salesforce to apply the change, then click Reconnect or save the credentials again.

"Requires a Salesforce-hosted My Domain instance URL"​

Server-to-server connections do not work with https://login.salesforce.com or https://test.salesforce.com. Use your org's My Domain URL from Salesforce Setup > My Domain.

redirect_uri_mismatch or invalid_client_id​

For redirect_uri_mismatch, copy the callback URL from Setup into your Salesforce app again. It must match exactly. For invalid_client_id, check the Instance URL: production and sandbox orgs use different login URLs.

The connection keeps asking to reconnect​

A user-authorization connection depends on a refresh token that Salesforce can expire. In the app's OAuth Policies, set Refresh Token Policy to Refresh token is valid until revoked. The lasting fix is to switch to Server-to-server.

Linked Members show no Salesforce values​

The scheduled poll does not read records that have not changed. On the Members tab, click Sync linked Members. Also check that Inbound is on and that your inbound rules are enabled.

Find matches returns nothing​

Check that Members have an email or phone, that matching Contacts or Leads exist in Salesforce with the same values, and that the connected user can read Contacts and Leads.

Agents cannot use the Salesforce tools​

The tools are available only when the header badge shows Connected. Use Reconnect in that header if needed; for a connected account, open its three-dot menu to find the action.