Overview
API Access Required
To use this integration, your Salesforce edition must have API Access. These are the only editions that include API access by default:
- Enterprise Edition
- Unlimited Edition
- Developer Edition
- Performance Edition
Our Salesforce integration enables you to leverage Salesforce fields in your Heap analysis and send usage activity from Heap into Salesforce. This integration is bi-directional and can be used for many use cases.
Syncing Salesforce Fields to Heap
This functionality allows you to import any built-in or custom fields on your Salesforce Account and Contact objects. These will map to accounts and users in Heap, respectively.
Step 1: Authentication (SFDC Admin Step)
You must have an Architect or Admin role in Heap to perform this step.
To set up our Salesforce integration, navigate to Integrations > Directory > Salesforce. On this page, click the Set Up button.
You will be redirected to log in with your Salesforce account and add Heap as an authorized client. Note that you must be a Salesforce admin to complete this step.
Step 2: Select a property to match users
Join Key Required
You need a user property to match data across the same user in Heap and this source. This property can be set to identity or any custom user property in Heap.
Make sure that the value of the property you choose is unique to each user. For example, email address is a typical join key because each user should have their own unique email address. You can use any two IDs that match.
You will need to use Heap’s APIs if you don’t have this kind of property set up or if you are not currently sending email addresses into Heap. Learn more about attaching custom data to users via Heap’s API here.
Need help? Please post in Community or contact us via the Get support page in Heap.
Choose between email and another unique identifier to match users between Heap and Salesforce.
Step 3: Configuring Fields to Sync to Heap
Once the authorization is approved, you can start adding contact and account properties to use in your analysis. Salesforce data is synced to Heap every hour at the top of the hour.
It may take up to several hours to import new Salesforce fields into Heap.
After the first sync, each time you add new properties, we’ll import that property for all contacts and accounts that have been active in Salesforce for 1 year before the day you set up the integration. Activeness is defined as the last update time of the contact and account record.
In the event that someone on your team deletes or renames a property in Salesforce that has already been imported into Heap, we will no longer sync data from that property or display it on the configuration page. However, you may still see the old property when running analysis. For assistance, visit our Get support page.
Syncing Events from Heap to Salesforce
This feature is only available to customers on the Premier plan or the Pro plan as an add-on. To upgrade, contact your Customer Success Manager or sales@heap.io
An SFDC admin should perform steps 1-3 & step 5 below.
Heap data is synced to Salesforce every 24 hours at midnight Pacific Time.
Step 1: Install the Heap Package (SFDC Admin Step)
Installation Link (for Production)
Installation Link (for Sandbox)
Please install the package for All Users. The Heap package contains two custom objects with two custom fields each:
| Object | Fields |
|---|---|
| Heap Account Usage | Account_Id Account |
| Heap Contact Usage | Contact_Id Contact |
Every new metric you send from Heap will appear as a new custom field on one of these custom objects.
Step 2: Set User Permissions on the Connecting User (SFDC Admin Step)
The connecting user needs permissions to add/remove fields and insert records into both the Heap Contact Usage and Heap Account Usage objects.
Please create a permission set with the following permissions enabled and then assign the permission set to the connecting user.
| System Permission | API Enabled (or API Only User) Customize Application Modify Metadata Through Metadata API Functions |
| Object Permission – Account | Object Permissions Read View All |
| Object Permission – Contact | Object Permissions Read View All Field Permissions Contact.Email (Read) |
| Object Permission – Heap Account Usage | Object Permissions Read Create Edit Delete View All Modify All |
| Object Permission – Heap Contact Usage | Object Permissions Read Create Edit Delete View All Modify All |
If you have already connected the Salesforce > Heap integration, you can modify the permissions on the connecting user and skip step 3.
Step 3: Authenticate in Heap (SFDC Admin Step)
You may skip this step if you have already authenticated in this Heap environment to enable the Salesforce source integration that syncs Salesforce fields to Heap.
You must have an Admin role in Heap to perform this step.
Navigate to Integrations > Directory > Salesforce. On this page, click the Connect button.
You’ll be redirected to log in with your Salesforce account and add Heap as an authorized client. Note that you must be a Salesforce admin to complete this step.
Once the authorization is approved, you’ll be redirected back to Heap to configure metrics to send to Salesforce.
Step 4: Configure activities to send to Salesforce
Note: You must be an Admin in Heap to complete this step.
Navigate to Integrations > Directory > Salesforce. You can configure user-level and account-level activities to send by specifying:
- Key event (e.g. session)
- Lookback period (e.g. in the past 7 days)
First, choose whether you want to send user or account activity data to SFDC.
Once you’re in the configuration screen, you can configure an activity by specifying the key event and lookback window.
Every metric will appear as a custom field on either the Heap Account Usage or Heap Contact Usage object depending on whether it’s a user-level or account-level metric.
Step 5: Grant field-level permissions in Salesforce for the new fields (SFDC Admin Step)
For any new metric configured in Step 4, an SFDC admin should find a corresponding new custom field on either the Heap Account Usage or Heap Contact Usage object. You can reference the field name in your Heap account.
You need to grant the connecting user read/edit access to the new fields for the integration run to succeed. You can adjust these permissions in the permission set:
After the integration run completes, you can roll up these metrics into user or account scores to incorporate usage data into your scoring.
Step 6 (optional): Enable Field History Tracking
By default, this integration does not keep track of how values have changed. For example, if yesterday the account had 10 instances, but today they have 5, then the record would only show 5.
You’ll have to enable field history tracking on Heap’s custom objects to record how the values change and use that information in custom logic. See Salesforce’s documentation on field history tracking to learn more.
Frequently Asked Questions
Does this integration work with Salesforce sandboxes?
Yes, you can connect to a Salesforce sandbox. We recommend connecting to a Salesforce sandbox from a Heap development environment, so that data from the sandbox does not pollute your Heap production environment.
How many API credits will the integration consume?
Our integration runs hourly and uses 2 credits to query the account and contact objects to check for changes, and then use 1 additional credit for every 2000 record changes within that hour. We impose a daily limit of using no more than 10,000 credits per day, though we almost never hit this limit.
We would like to create a new user to run this integration. What are the minimum permissions the SFDC user needs to have for the integration to work properly?
To send data from SFDC into Heap only: You can create a permission set with read and view all permissions for Contacts and Account objects, read permissions for all Contact and Account fields, and “API Enabled” under system permissions.
To send data from SFDC into Heap AND send data from Heap into SFDC: You can create a permission set with read and view all permissions for Contacts and Account objects, read permissions for all Contact and Account fields, and all permissions for Heap Contact Usage and Heap Account Usage objects and fields.
What if our Contact to Account relationship is not 1:1 (i.e. one Contact could belong to more than one Account)?
Heap will only maintain a 1:1 relationship between Contact and Accounts. This means the user in Heap connected to the Contact will be assigned the most recently updated Account.