> For the complete documentation index, see [llms.txt](https://docs.storylane.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.storylane.io/integrations-demo-suite/integrations-and-data-flow/salesforce/connecting-salesforce-to-storylane-admin-setup-guide.md).

# Connecting Salesforce to Storylane: Admin Setup Guide

### Overview <a href="#overview" id="overview"></a>

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 <a href="#before-you-start-choose-the-connecting-user" id="before-you-start-choose-the-connecting-user"></a>

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 <a href="#permissions-to-grant" id="permissions-to-grant"></a>

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 <a href="#object-and-field-access" id="object-and-field-access"></a>

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&#x20;

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 <a href="#what-storylane-creates-in-your-org" id="what-storylane-creates-in-your-org"></a>

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](https://docs.storylane.io/integrations-demo-suite/integrations-and-data-flow/salesforce/storylane-app-for-salesforce).

### Reconnecting when Storylane objects already exist <a href="#reconnecting-when-storylane-objects-already-exist" id="reconnecting-when-storylane-objects-already-exist"></a>

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 <a href="#after-connecting" id="after-connecting"></a>

**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 <a href="#security-review-reference" id="security-review-reference"></a>

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 <a href="#troubleshooting" id="troubleshooting"></a>

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.\ <br>

| 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                                                     |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.storylane.io/integrations-demo-suite/integrations-and-data-flow/salesforce/connecting-salesforce-to-storylane-admin-setup-guide.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
