Connecting Salesforce to Storylane: Admin Setup Guide
Overview
This guide is for the Salesforce admin connecting Storylane to your org. It covers who should connect, which permissions to grant, what Storylane creates in Salesforce, and how to fix common setup errors.
Once connected, Storylane finds the Lead or Contact matching each demo or Hub viewer's email and attaches their engagement data (time spent, completion, CTA clicks, buying intent) as a related record. Depending on your settings, it can also create a new Lead or Contact when no match exists.
What Storylane sends is limited by design:
Storylane sends the visitor's email, plus first and last name when Storylane captured them (usually from a form in your demo). If no last name was captured, it sends N/A. When it creates a Lead, it also sets Company to N/A. When it creates a Contact, it links the Contact to the Account whose website matches the email domain, if one exists. It also sends any extra required-field defaults configured for your workspace. Everything else it sends is engagement data. It never sends the visitor's company or country.
Storylane never updates or deletes your existing Lead, Contact, Account or Opportunity records. It only creates new Leads or Contacts (when enabled) and writes engagement data to Storylane's own custom objects, which link to the Lead or Contact.
Before you start: choose the connecting user
We recommend connecting with a dedicated Salesforce integration user rather than a personal login. Storylane syncs as whichever Salesforce user signs in during setup, so a dedicated user keeps the connection working if someone leaves or changes roles.
The integration user doesn't need a Storylane seat. A Storylane admin clicks Connect in Storylane, then signs in on the Salesforce login page with the integration user's credentials. You don't need to add that user to Storylane or provision it in your SSO.
The integration user must be able to sign in through a browser. Storylane connects with the standard OAuth 2.0 authorization code flow. Someone signs in as the integration user on the Salesforce login page and clicks Allow once. Storylane then stores a refresh token and syncs server to server. No further sign-ins are needed unless the token is revoked or you reconnect.
Use a standard Salesforce user license with API Enabled. The free Salesforce Integration license and users with API Only User turned on can't sign in through a browser, so they can't complete the connection. Salesforce also requires multi-factor authentication for browser sign-ins, so the person connecting needs access to the integration user's verification method.
Permissions to grant
The connecting user needs admin-level system permissions only while setup runs, and standard object access for everyday syncing. Grant them through a permission set (recommended) or the user's profile.
System permission
Why it's needed
Needed after setup?
API Enabled
Storylane reads and writes through the Salesforce API
Yes, always
Modify Metadata Through Metadata API Functions
Creates Storylane's custom objects, fields and page layouts
No, can be removed after connecting
Manage Profiles and Permission Sets
Creates a Storylane permission set for each custom object
No, can be removed after connecting
Assign Permission Sets
Assigns those permission sets to the connecting user
No, can be removed after connecting
Setup runs on every connection, not just the first one. It also runs again when you reconnect, or when a new Storylane feature adds a custom object. If you removed the setup permissions after connecting, either grant them again before reconnecting or ask Storylane support for a manual connection link (see Reconnecting when Storylane objects already exist).
Object and field access
For day-to-day syncing, the connecting user needs the object access below, plus field-level security on the listed fields. Fields Storylane only reads need Read. Fields Storylane writes when it creates a Lead or Contact need both Read and Edit. Read access alone is not enough for these, and Salesforce will reject the new record.
If field-level security hides a field on one of Storylane's custom objects, syncing stops and Storylane marks the connection as needing attention. If a Lead or Contact field is hidden or read-only, the connection stays active, but records won't be created or linked, so grant access to every listed field.
Object
Access
When it's used
Fields Storylane reads (Read)
Fields Storylane writes (Read + Edit)
Lead
Create, Read
Always: finds Leads by email, follows converted and merged Leads, creates a Lead if "create lead" is on
Id, Email, FirstName, LastName, IsConverted, ConvertedContactId, ConvertedAccountId, MasterRecordId, IsDeleted
Email, FirstName, LastName, Company, plus any required-field defaults configured for your workspace
Contact
Create, Read
Always: finds Contacts by email, follows merged Contacts, creates one when Contact is the target object
Id, Email, FirstName, LastName, MasterRecordId, IsDeleted
Email, FirstName, LastName, AccountId (Account Name), plus any required-field defaults configured for your workspace
Account
Read
Matches a new Contact to an existing Account by website domain, and supports deal sync
Id, Name, Website
None
StorylaneDemoData__c
Create, Read, Edit
Always: demo engagement
All Storylane fields on the object
All Storylane fields on the object
StorylaneHubData__c
Create, Read, Edit
If you use Hubs
All Storylane fields on the object
All Storylane fields on the object
StorylaneRepxData__c
Create, Read, Edit
If you use RepX
All Storylane fields on the object
All Storylane fields on the object
Opportunity, OpportunityContactRole, OpportunityStage, User
Read
Deal sync, which runs for every workspace by default. Missing access breaks deal sync only, not Lead or Contact syncing
Opportunity name, amount, stage, close date, owner, Description, LastActivityDate; contact Name and Email through OpportunityContactRole; stage definitions; User Profile.Name
None
CurrencyType
Read
Only on multi-currency orgs, to find the corporate currency
Corporate currency
None
Not using Deal Intelligence? You can leave out Opportunity, OpportunityContactRole, OpportunityStage and User. Ask Storylane support to turn off the deals sync for your workspace so it doesn't log daily permission errors.
Storylane's custom-object access is granted automatically through the permission sets created during setup and assigned to the connecting user, so you don't need to add it by hand. If you later switch to a different integration user, assign the same Storylane permission sets (for example, StorylaneDemoData_Permissions) to the new user.
Required-field defaults
Every workspace sends Last Name = N/A when no last name was captured, and Company = N/A on new Leads. If your org has other required fields or validation rules on Leads or Contacts, contact Storylane support to add default values for them. Any field Storylane sends a default for needs both Read and Edit for the integration user. If the user can’t read the field, Storylane drops the default, and Salesforce rejects the new record with REQUIRED_FIELD_MISSING.
What Storylane creates in your org
During setup, Storylane uses the Metadata API to create its own custom objects and the permissions to use them. It does not install a managed package.
Created in Salesforce
What it holds
Created when
StorylaneDemoData__c
Demo engagement per visitor: time spent, completion, CTA clicked, buying intent
Always
StorylaneHubData__c
The same engagement data for Storylane Hubs
If you use Hubs
StorylaneRepxData__c
RepX AI agent conversations: duration, topics, qualification, AI summary and transcript
If you use RepX
Fields and page layouts
The fields on each object above, plus a lookup to the related Lead or Contact
With each object
One permission set per object (e.g. StorylaneDemoData_Permissions)
Access to that object and its fields, assigned to the connecting user
With each object
The objects are unmanaged, so their API names have no namespace prefix. You'll find them in Setup > Object Manager under names starting with "Storylane".
The separate Storylane app on AppExchange is an optional add-on for getting a pre-loaded dashboard and a flow to transition the demo data object from a lead to a contact on conversion. Learn more about the Storylane app for Salesforce.
Reconnecting when Storylane objects already exist
If Storylane already created its custom objects in your org during an earlier connection, contact Storylane support for a manual connection link before you reconnect. This link skips creating the custom objects and fields and assigning the permission sets, so the connecting user doesn't need the setup permissions.
Reconnecting as a different Salesforce user? The manual link won't assign the Storylane permission sets to the new user. Before reconnecting, assign the existing Storylane permission sets (for example, StorylaneDemoData_Permissions) to that user yourself, or syncing will fail.
After connecting
Removing setup permissions. Once the connection succeeds, you can remove Modify Metadata Through Metadata API Functions, Manage Profiles and Permission Sets, and Assign Permission Sets from the integration user. Keep API Enabled, the object access, and the Storylane permission sets assigned during setup.
Changing sync settings. Settings such as the target object (Lead or Contact), whether Storylane creates new records or only updates existing ones, and a sync delay are configured by Storylane. Contact Storylane support to change them.
Switching between sandbox and production. If you switch the connection between environments, for example from a sandbox to production, inform Storylane support first so we can clear the references to previously synced records.
How records are matched. Storylane matches visitors to records by email. By default, a matching Contact takes priority over a matching Lead. If several Leads or Contacts share one email, only one of them gets the demo data, and which one isn't predictable. If you need it on every matching record, a Salesforce Flow can copy it across.
Automations that delete Leads. If your org deletes certain Leads soon after creation (for example, internal email domains), Storylane can't find them again and may create them repeatedly. Tell support which domains you exclude so they can advise on the best setup.
Security review reference
You don't need to create your own Connected App or External Client App. Storylane connects through its own app, and these details are for your security review or API access policies.
The Storylane app isn’t installed in your org until someone authorizes it for the first time, and Salesforce blocks non-admin users from approving an uninstalled app. Give the connecting user the “Approve Uninstalled Connected Apps” permission for the first sign-in. After connecting, you can install the Storylane app under Setup > Connected Apps OAuth Usage, set its policies there, and remove that permission. If the integration user’s profile has Login IP Ranges, set the Storylane app’s IP Relaxation policy to “Relax IP restrictions” so Storylane’s servers can keep syncing.
Item
Value
OAuth scopes
Access and manage your data (api); Perform requests on your behalf at any time (refresh_token, offline_access)
Callback URL
https://connect.storylane.io/oauth/salesforce/callback
Writes to standard objects
Creates Leads or Contacts only, when enabled. Never updates or deletes existing Lead, Contact, Account or Opportunity records
Access to Storylane's custom objects
The auto-created permission sets grant Read, Create, Edit, Delete, View All and Modify All on Storylane's own objects only
Need the consumer key to allowlist Storylane under API Access Control? Contact Storylane support.
The OAuth scopes control what the app may request. What Storylane can actually access is still limited by the connecting user's permissions.
Troubleshooting
In Storylane, most setup failures show only as "Failed to connect to Salesforce". Storylane support can see the exact Salesforce error, so share the time you tried and the user you signed in with.
Salesforce error
What it means
Fix
INSUFFICIENT_ACCESS: use of the Metadata API requires a user with the ModifyAllData or ModifyMetadata permissions
The connecting user can't create Storylane's custom objects
Grant Modify Metadata Through Metadata API Functions, then reconnect
CANNOT_INSERT_UPDATE_ACTIVATE_ENTITY: entity type cannot be inserted: Permission Set Assignment
Objects were created, but the user can't assign the Storylane permission set to itself
Grant Assign Permission Sets, then reconnect
"Insufficient Privileges" at sign-in, or an OAuth or app-approval error
The connecting user isn't allowed to approve the Storylane app, which isn't installed in your org yet
Grant Approve Uninstalled Connected Apps for the first sign-in, then install the Storylane app from Connected Apps OAuth Usage
The integration user can't sign in on the Salesforce login page
The user is on the Salesforce Integration license or has API Only User turned on
Use a standard Salesforce user license with API Enabled, and turn off API Only User
Connection shows "needs attention" after it was working
Field-level security hides a field on a Storylane custom object, or the connection's authorization failed
Give the integration user access to all fields on the Storylane objects, or reconnect
Daily errors on Opportunity or User fields
Deal Intelligence sync can't read those objects
Grant read access, or ask support to turn off the deals sync
Records don't sync after switching between sandbox and production
Storylane still holds references to records in the previous org
Contact support to clear the old references
Leads hold only an email, or a name and email
Expected: Storylane sends only email and, when captured, first and last name
Contact support to switch to update-only mode or add a sync delay, so your form creates the Lead first
INVALID_FIELD: No such column 'Email' on entity 'Contact' (or 'Lead')
The integration user can't read that field, so Storylane can't look up records by email
Grant Read on the field named in the error
INVALID_FIELD_FOR_INSERT_UPDATE: Unable to create/update fields: [field]
The user can read the field but can't write it, so new Leads or Contacts can't be created
Grant Edit on the field named in the error. See the "Fields Storylane writes" column above
REQUIRED_FIELD_MISSING
Your org requires a field Storylane doesn't fill, or a default was dropped because the user can't read that field
Contact support to add a default for the field, and grant Read and Edit on it
Demo data appears for some visitors but not others
Usually a write permission is missing, for example AccountId, which is only set when the visitor's domain matches an Account
Grant Read and Edit on every field in the "Fields Storylane writes" column
Last updated
Was this helpful?