For the complete documentation index, see llms.txt. This page is also available as Markdown.

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?