Salesforce, Data 360 and Marketing Cloud
How to connect Salesforce (Sales and Service Cloud), Salesforce Data 360 and Salesforce Marketing Cloud Engagement: what your Salesforce admin installs, the options, what people can read and change, and what error messages mean.
At a glance
| Connects through | Sign-in | Network | Status | First test question | |
|---|---|---|---|---|---|
| Salesforce | Salesforce REST API | Personal sign-in | Nothing to open | Verified | "Show my 5 most recently changed opportunities in salesforce:prod." You see opportunities you can see in Salesforce. |
| Data 360 | Salesforce Data 360 Query API, signed in through Salesforce | Personal sign-in | Nothing to open | Available | "Which Data 360 objects can I read in data360:prod?" You see data model objects ending in __dlm. |
| Marketing Cloud | Marketing Cloud REST API | Personal sign-in | Nothing to open | Pilot | "Which data extensions can I read in sfmc:main?" You see your data extensions. |
Add each source with the usual steps. The network answers are explained in What your network needs. If the first test question fails, the error message tells you what to fix: look it up under When something goes wrong below.
Salesforce
Each person signs in with their own Salesforce login (OAuth with PKCE). Salesforce then applies their profile, permission sets, field-level security and sharing rules to everything SourceLace reads or changes.
Two ways to sign people in
Salesforce only lets people sign in through an app (an External Client App) that belongs to their org, so each Salesforce source uses one of two apps. Choose one per source:
| Route 1: SourceLace's app (the default) | Route 2: your own app | |
|---|---|---|
| What your Salesforce admin does | Installs SourceLace's app, delivered as a managed package (a bundle), once per org, from a link support sends. | Creates an External Client App in your own org (Distribution State Local). Nothing is installed. |
| What your SourceLace admin enters | The My Domain address (login_url). |
The My Domain address, and the app's Consumer Key (and Consumer Secret if the app requires one). |
| Choose it when | You want the quickest setup, and SourceLace maintains the app and its scopes. | Your security team wants the app to live in your org and under your control, or you cannot install a package. |
Both routes give the same result: each person signs in with their own Salesforce login and sees only what Salesforce lets them see. Route 1 is what happens when the Consumer Key option on the source is empty. The steps for Route 1 follow; the steps for Route 2 are under Use your own Salesforce app.
What your admin does in Salesforce (Route 1: SourceLace's app)
SourceLace signs people in through its own Salesforce External Client App, delivered as a managed package. Salesforce only lets people use an app that is installed in their org, so your Salesforce admin installs it once per org. It takes about 15 minutes. Trying it in a sandbox first is a good habit.
Who: a Salesforce admin with the System Administrator profile, or a user with the permissions Download AppExchange Packages, Customize Application and Assign Permission Sets.
Before you start, check:
- Your Salesforce edition can use the API: Enterprise, Unlimited, Performance or Developer edition. (Professional edition needs Salesforce's API add-on.)
- Everyone who will use SourceLace has the user permission API Enabled, through their profile or a permission set. Without it, sign-in works but every question fails with
API_CURRENTLY_DISABLED. - You have the install link. Ask support@sourcelace.com for it.
Steps:
- Install the package. Open the install link while logged in to the org. For a sandbox, change
login.salesforce.comin the link totest.salesforce.comfirst. Choose Install for Admins Only (people get access in step 4), tick that you understand the package is not authorized for distribution through AppExchange, and click Install. Check: Setup → Installed Packages lists SourceLace. - Check the app and its scopes. Go to Setup → External Client App Manager and open SourceLace. On Settings → OAuth Settings, the selected scopes are Manage user data via APIs (api), Perform requests at any time (refresh_token, offline_access), and, for Data 360, Perform ANSI SQL queries on Data 360 data (cdp_query_api) and Manage Data 360 profile data (cdp_profile_api). (Salesforce may still call the last two "Data Cloud" or "Customer Data Platform".) You cannot edit these: they come with the package. If the Data 360 scopes are missing and you will use Data 360, ask support for the current install link and install it over the old version.
- Open the app's policies. On the same app, go to Policies → Edit.
- Decide who may use it. Under OAuth Policies → Permitted Users, choose one:
- Admin approved users are pre-authorized (recommended). Save, then create a permission set: Setup → Permission Sets → New, label it for example "SourceLace users", and save. In the permission set, open Assigned Connected Apps (in newer releases Assigned External Client Apps), click Edit, add SourceLace, and save. Then click Manage Assignments → Add Assignment, tick the people who will use SourceLace, and click Assign.
- All users may self-authorize. Nothing more to do: each person approves the app the first time they connect.
- Optional: under IP Relaxation, Session Timeout and Refresh Token Policy, set your own security standard. SourceLace works with the defaults. If you choose Enforce IP restrictions, ask support for SourceLace's outbound IP addresses and add them to the people's profiles under Login IP Ranges, or sign-in fails with "ip restricted".
- Copy the address SourceLace needs. Go to Setup → My Domain and copy Current My Domain URL, such as
https://corvanta.my.salesforce.com. Give it to your SourceLace admin for thelogin_urloption below.
Check that it worked: one person who has the permission set (or any person, with self-authorize) opens My connections in SourceLace, connects the source, and asks the first test question from At a glance. In Salesforce, Setup → Login History then shows their login with the application SourceLace. If it fails, find the message under When something goes wrong below.
Exact labels can differ a little between Salesforce releases. Salesforce's own guide is in Salesforce Help: search for "External Client App OAuth policies" and "Assign a permission set".
SourceLace's redirect URL (https://mcp.sourcelace.ai/connect/callback) travels with the package, so nobody types it in. The app requires PKCE.
Use your own Salesforce app (Route 2)
Use this instead of Route 1 when your Salesforce admin creates the app in your own org. SourceLace never sees your admin's Salesforce login: your SourceLace admin only enters the app's Consumer Key (a public identifier, not a password) and, if the app requires one, its Consumer Secret (stored encrypted and never shown again). The app works only in the org it was created in; a sandbox needs its own app and its own source.
Who: a Salesforce admin with the System Administrator profile (or another profile Salesforce lets create External Client Apps: Salesforce Help names the permission). Your SourceLace admin does the last step.
Before you start, check: your edition can use the API and everyone who will use SourceLace has API Enabled (see Route 1, Before you start, check). You know the address your people open SourceLace at: the app's callback URL must match it.
Steps in Salesforce:
-
Start a new app. Go to Setup → External Client App Manager → New External Client App. Check: the form asks for a name and contact email.
-
Basic information. External Client App Name: any name, such as
SourceLace. Contact Email: your admin's address. Distribution State: Local. (Local means the app lives only in this org: no package, nothing to install.) -
Turn on OAuth. Under API (Enable OAuth Settings), tick Enable OAuth.
-
Callback URL. Enter
https://mcp.sourcelace.ai/connect/callbackexactly: same address, no extra space or trailing slash. It must be the address your people open SourceLace at. If your organization uses more than one SourceLace address, add one callback URL per line. -
OAuth scopes. In Available OAuth Scopes select, and use the arrow to move to Selected OAuth Scopes, exactly these:
- Manage user data via APIs (api): always.
- Perform requests at any time (refresh_token, offline_access): always. Without it, Salesforce refuses the sign-in with
OAUTH_APPROVAL_ERROR_GENERIC. - For Data 360 sources only: Perform ANSI SQL queries on Data 360 data (cdp_query_api) and Manage Data 360 profile data (cdp_profile_api). (Salesforce may still call these "Data Cloud" or "Customer Data Platform".) One app can serve both your Salesforce and your Data 360 sources, so add these two if you will ever use Data 360.
No other scope is needed. Do not add the identity scope or any Agent scope: SourceLace does not ask for them.
-
Flow enablement. Tick Enable Authorization Code and Credentials Flow. Leave the other flows off.
-
Security. Leave Require Proof Key for Code Exchange (PKCE) extension for Supported Authorization Flows ticked (SourceLace always uses PKCE, a check that protects the sign-in code). Main path, the simplest: leave Require secret for Web Server Flow and Require secret for Refresh Token Flow unticked, and later enter only the Consumer Key in SourceLace. If your security team wants a secret kept: tick both boxes and later enter the Consumer Secret in SourceLace too. The two boxes must match what you enter: ticked means SourceLace needs the secret (otherwise Salesforce answers
invalid_client); unticked means no secret is needed (a secret entered anyway is harmless but unnecessary). Leave Refresh Token Rotation as Salesforce sets it: SourceLace keeps the new refresh token each time Salesforce sends one. -
Create the app. Click Create. Check: the app appears in External Client App Manager with Distribution State Local.
-
Decide who may use it. Open the app, go to Policies → Edit, and under OAuth Policies → Permitted Users choose All users can self-authorize (each person approves the app the first time they connect), or Admin approved users are pre-authorized and follow Route 1, step 4, to give a permission set the app (Assigned External Client Apps) and assign it to your people. Save.
-
Copy the Consumer Key (and Secret). On the app's Settings tab, open OAuth Settings, click Consumer Key and Secret, and, if Salesforce asks, enter the verification code it emails to you. Copy the Consumer Key (about 85 letters and digits, starting
3MVG). If you chose the secret option in step 7, copy the Consumer Secret too. Give them to your SourceLace admin over a channel your organization trusts for secrets, not in chat or email text that is kept.
Steps in SourceLace (your SourceLace admin):
- On Connections, add a Salesforce (or Data 360) source, or open an existing one. Enter the My Domain address in Sign-in address, paste the Consumer Key into Your own Salesforce app's Consumer Key, and the Consumer Secret into Its Consumer Secret if the app requires one. Save. Check: a wrong-looking key is refused straight away with a plain message; the secret then shows as saved and is never displayed again.
Check that it worked: one person connects the source on My connections. Salesforce shows its Allow Access? screen for your app's name; the person clicks Allow, and the source shows Connected. In Salesforce, Setup → Login History shows their login with the application name you chose in step 2. If something fails, look up the message under When something goes wrong.
To go back to Route 1, empty the Consumer Key on the source and save: the stored Consumer Secret is removed too. Entering a different Consumer Key (another app) also removes the stored secret: enter the new app's secret too if it requires one. Whenever a source changes app, each person's saved sign-in belonged to the old app, so SourceLace may ask them to connect again.
Salesforce's own guide is in Salesforce Help: search for "External Client Apps" and "OAuth settings for an external client app". Exact labels can differ a little between Salesforce releases.
Add the source (SourceLace admin)
On Connections → Add a source, choose Salesforce, or ask in chat: "Add a SourceLace source salesforce:prod, kind salesforce, label Corvanta Salesforce, login URL https://corvanta.my.salesforce.com".
| Option | Type | Default | Example | What it is |
|---|---|---|---|---|
login_url |
Address | https://login.salesforce.com |
https://corvanta.my.salesforce.com |
Where people sign in. The org's My Domain (https://<name>.my.salesforce.com) works for everyone and is the safest choice. https://login.salesforce.com works for most production orgs, and https://test.salesforce.com (or the sandbox's My Domain, https://<name>--<sandbox>.sandbox.my.salesforce.com) for sandboxes. |
client_id |
Text | empty | 3MVG9... |
Optional. The Consumer Key of your own Salesforce app (Route 2). Empty means SourceLace's app. |
client_secret |
Secret | empty | Optional, only with client_id, and only if your app requires a secret. Stored encrypted and never shown again; leave it empty when editing to keep the saved one. A new client_id (another app) keeps no saved secret: enter the new app's secret if it requires one. |
Only Salesforce's own addresses are accepted. A Lightning address copied from the browser (https://<name>.lightning.force.com) is turned into the matching My Domain automatically. After someone signs in, SourceLace sends every request to the org address Salesforce gives back, so the login address only matters for signing in.
What people can do
- Find objects and fields:
search_schemaanddescribe_objectlist standard and custom objects and fields, picklist values and relationships, limited to what the person can see. - Query: one SOQL
SELECT, such asSELECT Name, Amount FROM Opportunity WHERE IsClosed = false ORDER BY Amount DESC LIMIT 20. Anything that is not a single read-only SOQL query is refused before Salesforce is called. - Read a record:
get_recordwith an 18- or 15-character record id, plus up to 3 related lists. - Search everything: where it is on, Searching everything also searches accounts, contacts, opportunities, leads and cases with Salesforce's own search, with the person's own access.
- Change records (create, update, delete), only on objects your SourceLace admin made writable (such as
Account, Opportunity, Case). The preview checks the person's object and field permissions and, for existing records, their sharing access. An update is refused if the record changed in Salesforce after the preview. The result includes the previous values, so a change can be undone; deleted records go to Salesforce's Recycle Bin.
Receive events (for agents that start on Salesforce events)
The person whose sign-in an agent uses must be able to see the events it listens to. Their sign-in gives access; the Salesforce admin decides what that person may see.
- Platform events and platform event channels: the person needs read access to the platform event (its object permission Read, through their profile or a permission set).
- Change events: Change Data Capture must be switched on for each object in Salesforce Setup, under Change Data Capture, and the person needs read access to that object and to the fields the agent reads. Changes to fields the person cannot see are not shown to them.
- Nothing to install. SourceLace receives the events with the same connected app and sign-in as the rest of the source. No Flow, Apex or Named Credential is needed.
If the access is removed, the agent stops receiving events and its page asks its owner to reconnect Salesforce.
When something goes wrong
A refused sign-in shows Salesforce's reason and its error code, and, where SourceLace can tell, what to do, such as "Sign-in was not completed: An unexpected error has occured during authentication (error OAUTH_APPROVAL_ERROR_GENERIC). Your Salesforce admin gives you SourceLace's permission set...". Look up the code first.
| What you see | What it means | What to do |
|---|---|---|
OAUTH_APP_BLOCKED, or "app is not installed" |
The package is not installed in the org the person signed in to, or the app is blocked there. | Install the package in that org (step 1). If people sign in to a sandbox, it needs its own install. Check that login_url is that org's address. |
OAUTH_APPROVAL_ERROR_GENERIC, or "user is not admin approved" |
Salesforce refused to approve the sign-in. It has two causes. (1) Permitted Users is Admin approved users are pre-authorized and the person does not have the permission set. (2) With your own app (Route 2): the app is missing a scope, most often Perform requests at any time (refresh_token, offline_access), even when Permitted Users is All users can self-authorize. On a Data 360 source while Salesforce works: see Data 360. | (1) Give the person the permission set from step 4 (Manage Assignments → Add Assignment), and check it lists the app under Assigned Connected Apps (Assigned External Client Apps in newer releases). (2) Open Setup → External Client App Manager → your app → Settings → OAuth Settings and move to Selected: Manage user data via APIs (api) and Perform requests at any time (refresh_token, offline_access) (and the two Data 360 scopes for Data 360). Then the person connects again. |
OAUTH_AUTHORIZATION_BLOCKED, or "Cross-org OAuth flows are not supported for this external client app" |
The app the source uses was created in a different Salesforce org and is not installed in this one. | With your own app: create the app in this org (Route 2, step 1) with Distribution State Local, and enter its Consumer Key on the source. Or empty the Consumer Key to use SourceLace's app (Route 1, which needs the package installed). |
access_denied, or "end-user denied authorization" |
The person clicked Deny on Salesforce's approval page. | Connect again and click Allow. |
redirect_uri_mismatch |
The callback URL Salesforce has for the app is not the one SourceLace sends. With SourceLace's app (Route 1): the redirect URL in the installed package is not SourceLace's. With your own app (Route 2): the app's Callback URL is different. | Route 1: contact support, who send a new install link. Route 2: in the app's Settings → OAuth Settings, set Callback URL to https://mcp.sourcelace.ai/connect/callback exactly, the address your people open SourceLace at. |
invalid_client_id, or "client identifier invalid" |
Salesforce does not know the app in this org. Route 1: usually the package is not installed there, or login_url points at a different org (a sandbox instead of production). Route 2: the Consumer Key on the source is wrong, or belongs to an app in another org. |
Route 1: install the package in the org (step 1), and set login_url to that org's My Domain. Route 2: copy the Consumer Key again (Route 2, step 10) and check login_url is the org the app was created in. |
invalid_client, or "client authentication failed" |
Route 2: the app requires a secret (Require secret for Web Server Flow or Refresh Token Flow is ticked) and the Consumer Secret on the source is missing or wrong. | Copy the Consumer Secret again (step 10) into the source, or untick both secret settings in the app (step 7). |
invalid_scope |
Route 2: the app does not allow every permission SourceLace asks for. | Move the scopes in step 5 to Selected. (For a refused approval page, see OAUTH_APPROVAL_ERROR_GENERIC above: Salesforce often answers that instead.) |
invalid_grant |
The sign-in code or saved sign-in was already used, expired or was revoked. | Connect again. If it fails every time with your own app, check the callback URL and that PKCE is ticked (steps 4 and 7). |
| "...: client_id must be the Consumer Key of your Salesforce app ..." | The Consumer Key on the source is not shaped like one. | Copy it again from Settings → OAuth Settings → Consumer Key and Secret (step 10): letters and digits only, usually starting 3MVG. |
| "A Consumer Secret needs the Consumer Key of the same Salesforce app." | A secret was entered without a key. | Enter the Consumer Key too, or leave both empty to use SourceLace's app. |
| "SourceLace's Salesforce app is not set up yet. Give ... your own Salesforce app's client_id ..." | SourceLace's own app is not available on this SourceLace and the source has no Consumer Key. | Enter your own app's Consumer Key (Route 2), or contact support. |
| "Salesforce sign-in did not work at ...: it answered with a redirect (or a web page) instead of a token. Check the login URL ..." | login_url is mistyped, or the org's My Domain changed. |
Copy the current address from Setup → My Domain into login_url. Or use https://login.salesforce.com. |
| "The Salesforce login URL for ... must be login.salesforce.com, test.salesforce.com, or the org's My Domain" | Only Salesforce's own addresses are accepted in login_url. |
Use the org's My Domain, such as https://corvanta.my.salesforce.com. |
| "The Salesforce login URL for ... must be a plain https:// address." | login_url has a path, port or ?.... |
Keep only https://<name>.my.salesforce.com. |
| "Salesforce sign-in failed: authentication failure" | Salesforce refused the person's login: the account is locked or frozen, or the sign-in came from an address the person's profile does not allow. | In Setup → Users, unlock or unfreeze the user. Check Login IP Ranges on their profile (step 5). |
| "Salesforce sign-in failed: ip restricted" | The app's IP Relaxation is Enforce IP restrictions, and SourceLace's addresses are not in the person's Login IP Ranges. | Add SourceLace's outbound IP addresses (ask support) to the profile's Login IP Ranges, or set IP Relaxation to Relax IP restrictions (step 5). |
| "Salesforce sign-in failed: inactive user" | The person's Salesforce user is deactivated. | Reactivate the user in Setup → Users, or use another login. |
| "Salesforce sign-in failed: expired access/refresh token" | The refresh token ended under the app's Refresh Token Policy, or an admin revoked it. | Connect again. To make sign-ins last longer, change the Refresh Token Policy (step 5). |
| "Salesforce sign-in failed: ..." (another reason) | Salesforce's own reason follows. | Look up the words in Salesforce Help. Often the person's profile cannot use the app (step 4) or the account is locked. |
| "Salesforce answered with a web page instead of data ... The org may be under maintenance, or its address changed" | The org is under maintenance, or moved. | Wait for maintenance to end (Salesforce Trust shows it), or connect again on My connections. |
| "Salesforce moved this org to a new address." or "Your Salesforce session has expired." | The org moved, or the session ended. | SourceLace refreshes the sign-in itself. If it then asks, connect again. |
| "Salesforce: API_CURRENTLY_DISABLED: ..." | The person's user does not have the permission API Enabled. | Add API Enabled to their profile or to the SourceLace permission set (System Permissions). |
| "Salesforce: API_DISABLED_FOR_ORG: ..." | The org's edition cannot use the API. | Use an edition with API access, or buy Salesforce's API add-on (see Before you start). |
| "Salesforce: REQUEST_LIMIT_EXCEEDED: ..." | The org used up its daily API request limit (shared by every app in the org). | Wait: the limit counts the last 24 hours. Setup → Company Information → API Requests, Last 24 Hours shows the use. Ask Salesforce for a higher limit if it happens often. |
| "Salesforce: INSUFFICIENT_ACCESS_OR_READONLY: ..." or "Salesforce: INSUFFICIENT_ACCESS_ON_CROSS_REFERENCE_ENTITY: ..." | The person's profile, permission sets or sharing do not allow this on that record. | Change their access in Salesforce if they should have it. |
| "Salesforce: INVALID_TYPE: ..." | The object does not exist, or the person cannot see it. | Check the name with search_schema; give the person object access in Salesforce if they should see it. |
| "Salesforce: MALFORMED_QUERY: ..." or "Salesforce: INVALID_FIELD: ..." | Salesforce's own message about the query. | The AI usually fixes the query itself. |
| "Salesforce returned HTTP 503." (or another number) | Salesforce had a problem or is under maintenance. | Try again later; check Salesforce Trust. |
| "Your Salesforce user cannot update Opportunity records." (or create, delete) | The person's Salesforce profile does not allow it. | Change their permissions in Salesforce if they should. |
| "Your Salesforce user cannot update this ... record (sharing rules)." | Sharing does not give the person edit or delete access to that record. | Ask the record's owner or your Salesforce admin for access. |
| "... cannot be set on update (read-only or not permitted for you)." | That field is read-only for the person in Salesforce. | Change field-level security in Salesforce if they should edit it. |
| "This ... record changed in Salesforce after the preview. Propose the change again." | Someone else changed the record. | Ask for a new preview. |
| "Salesforce did not say which organization this sign-in is for." | Salesforce's answer to the sign-in did not name the org it belongs to, so SourceLace cannot tie the sign-in to your account. | Connect again. If it repeats, contact support. |
| "Salesforce sent back data in an unexpected shape.", "Salesforce returned an unexpected link." or "SourceLace refused to call an unexpected Salesforce address." | Salesforce's answer was not in the form SourceLace expects, or it pointed to an address outside Salesforce, which SourceLace never follows. | Try again shortly. If it repeats, contact support. |
Data 360
Status: Available. Built on Salesforce's published Data 360 APIs, and validated in your org during onboarding.
Data 360 (formerly Data Cloud) lives inside your Salesforce org, so it uses the same app and the same sign-in as Salesforce: SourceLace signs the person in to Salesforce, then exchanges that sign-in for a Data 360 token for the same person, so Data 360 still decides what each person can see. Read-only.
What your admin does in Salesforce for Data 360
Who: a Salesforce admin with the System Administrator profile (or Customize Application and Assign Permission Sets).
Before you start, check: Data 360 is set up in the org (Setup → Data 360 Setup, called Data Cloud Setup in older releases, shows it as provisioned), and the Salesforce steps above are done.
Using your own Salesforce app (Route 2)? Then there is no package: in your app's Settings → OAuth Settings, check Selected OAuth Scopes also include Perform ANSI SQL queries on Data 360 data (cdp_query_api) and Manage Data 360 profile data (cdp_profile_api) (added to the two every app needs, step 5 of Use your own Salesforce app), and enter the same Consumer Key on the Data 360 source. One app serves both your Salesforce and your Data 360 sources. Then continue with step 2 below, and skip step 1.
- Install the SourceLace package, or check it is current. Follow What your admin does in Salesforce, steps 1 to 4. In step 2, make sure the app's scopes include cdp_query_api and cdp_profile_api. If they are missing, the package is older than Data 360 support: ask support for the current install link and install it over the old one.
- Give each person a Data 360 permission set. Go to Setup → Permission Sets, open a Data 360 permission set such as Data Cloud User (read data) or Data Cloud Admin (names vary by release), click Manage Assignments → Add Assignment, tick the people, and click Assign. The permission set must also give access to the data spaces they should read (in the permission set, Data Space Permissions, often default).
- If Permitted Users is "Admin approved users are pre-authorized" (step 4 above), check the same people also have the SourceLace permission set, and that it lists SourceLace under Assigned Connected Apps. A person needs both: the SourceLace permission set to sign in, and the Data 360 one to read Data 360.
- Copy the address SourceLace needs: the same My Domain URL as for Salesforce (Setup → My Domain → Current My Domain URL).
Check that it worked: a person with both permission sets connects the Data 360 source on My connections and asks the first test question from At a glance. They see data model objects ending in __dlm. If they connected before Data 360 was set up, they connect again.
Salesforce's own guide is in Salesforce Help: search for "Data 360 permission sets" and "data spaces".
Add the source (SourceLace admin)
On Connections → Add a source, choose Data 360 (data360). It has the same options as Salesforce: login_url (the org's My Domain) and, to use your own Salesforce app instead of SourceLace's, client_id and client_secret (Route 2).
What people can do
search_schemaanddescribe_objectlist data model objects (names ending in__dlm), data lake objects (__dll) and calculated insights (__cio), with their fields.querytakes one SQLSELECT(orWITH ... SELECT), such asSELECT ssot__FirstName__c FROM ssot__Individual__dlm LIMIT 10. Anything that could change data and anything with more than one statement is refused before it reaches Data 360.get_recordlooks a row up by the object's primary key, and can add rows from related objects.
When something goes wrong with Data 360
| What you see | What it means | What to do |
|---|---|---|
OAUTH_APPROVAL_ERROR_GENERIC on a Data 360 source that uses your own app, while the Salesforce source still connects |
Your app lacks the two Data 360 scopes, or the person is not approved to use it. | In your app's Settings → OAuth Settings, move to Selected Perform ANSI SQL queries on Data 360 data (cdp_query_api) and Manage Data 360 profile data (cdp_profile_api) as well as the two every app needs. If Permitted Users is Admin approved users are pre-authorized, check the person has the permission set that lists your app. Then connect again. |
OAUTH_APPROVAL_ERROR_GENERIC on the Data 360 source, while the Salesforce source still connects ("...Data 360 asks Salesforce for two more permissions than Salesforce...") |
Salesforce refused the Data 360 sign-in, which asks for two more scopes than Salesforce: the SourceLace app in this org does not include the Data 360 scopes, or the person is not approved to use it. | In Setup → External Client App Manager → SourceLace → Settings → OAuth Settings, check the scopes include cdp_query_api and cdp_profile_api; if not, install the current package (ask support for the link). If Permitted Users is Admin approved users are pre-authorized, check the person has the SourceLace permission set and that it lists SourceLace under Assigned Connected Apps. Then the person connects again. |
| "Data 360 sign-in failed... Check that Data 360 is on in this org, that you have a Data 360 permission set, and that SourceLace's app has the cdp_query_api and cdp_profile_api scopes." | The person signed in to Salesforce, but Salesforce refused to give them a Data 360 token. | Check, in this order: Data 360 is provisioned (Setup → Data 360 Setup); the person has a Data 360 permission set (step 2); the app has the Data 360 scopes (step 1). If they connected before Data 360 was set up, connect again. If it still fails, contact support with the reason in the message. |
| "Salesforce did not return the org's address." or "Data 360 did not return a valid endpoint for this org." | Data 360 is not fully set up in the org, or Salesforce answered unexpectedly. | Check Setup → Data 360 Setup shows Data 360 as provisioned, then connect again. If it still fails, contact support. |
| "Your Data 360 sign-in has expired." or "Your Data 360 session has expired." | The Data 360 token ended. | SourceLace refreshes it itself. If it then asks, connect again. |
| "Data 360 has no object called ... that you can read. Try search_schema." | The object name is wrong, or the person's data space permissions do not include it. | Check the name with search_schema. Give the person the data space in their Data 360 permission set if they should see it. |
| "Data 360: ...: ..." | Data 360's own message about the query, such as an unknown column. | The AI usually fixes the query itself. |
| "Data 360 could not finish the query (...)." | Data 360 stopped the query. | Try again, or a narrower query. |
| "Data 360 is taking too long to run this query. Try a narrower query." | The query ran past the time limit. | Add filters or a LIMIT. |
| "Data 360 returned HTTP 503." (or another number) | Data 360 had a problem or is under maintenance. | Try again later; check Salesforce Trust. |
| "Data 360: no ... record has ... = '...'." | A lookup by value found no row, or the person's permission sets do not let them see it. | Check the value, and that the person's Data 360 permission set covers that data space. |
| "Data 360 returned an unexpected link." or "Data 360 returned an unexpected query id." | Data 360's answer was not in the form SourceLace expects. | Try again shortly. If it repeats, contact support. |
Marketing Cloud
Status: Pilot. Built on Marketing Cloud's documented API and tested against a simulated Marketing Cloud, so it is offered to one pilot customer at a time, on request. It has not been tried on a real account yet: tell support@sourcelace.com before you start, and we switch it on for your organization (until then, a Marketing Cloud source cannot be added). Marketing Cloud Engagement is a separate account from your Salesforce org, with its own logins, so it uses its own app. Each person signs in with their own Marketing Cloud login, and Marketing Cloud applies their roles and business unit access. Everything is read-only.
How this differs from Salesforce
There is no SourceLace-wide app for Marketing Cloud. Your Marketing Cloud admin creates an app (an installed package) inside your own Marketing Cloud account, and your SourceLace admin types its Client Id and Client Secret into the source.
- The Client Secret is stored encrypted with your organization's own key. After saving, SourceLace only ever shows
(saved). To keep it when editing the source, leave the field empty; to change it, type the new one. - Type the secret on the web app's Connections page, not in a chat and not in an email, so it never sits in a transcript or an inbox. Nobody at SourceLace needs to see it.
The redirect URL Marketing Cloud asks for is:
https://mcp.sourcelace.ai/connect/callback
What your admin does in Marketing Cloud
Once per Marketing Cloud account. About 15 minutes.
Who: a Marketing Cloud user with the Administrator role (or Marketing Cloud Administrator) in the parent account, who can open Setup → Platform Tools → Apps → Installed Packages. Without that role the menu is missing: ask your Marketing Cloud administrator.
Steps:
- Go to Setup → Platform Tools → Apps → Installed Packages and click New. Name:
SourceLace. Save. - On the new package, click Add Component, choose API Integration, click Next, then choose Web App and click Next. (Not Server-to-Server: that type has no sign-in for people.)
- Under Redirect URIs, enter the redirect URL above exactly, with nothing after it.
- Under the permissions (scopes), give it read access only: tick Read for Data Extensions, Journeys, Saved Content and Email, plus SMS if you use SMS. Leave every Write, Send and Delete box unticked. Save. Exact labels can differ a little between Marketing Cloud releases; if an error later names a permission, tick its Read box (see the table below).
- Open the component's Access (or the package's business unit access) and give the package the business units people will read. By default it has the one you are in.
- Copy these four things from the package, to enter on the SourceLace Connections page (the next section):
- Client Id and Client Secret from the Web App component.
- Authentication Base URI, such as
https://mc1a2b3c4d5e6f.auth.marketingcloudapis.com/. Thesubdomainoption is only the part before.auth.marketingcloudapis.com, heremc1a2b3c4d5e6f. - For a business unit other than the parent, its MID, the number shown under your account name, top right in Marketing Cloud. This is the optional
account_idoption.
Check that it worked: your SourceLace admin adds the source (next section). Then one person clicks Connect on My connections, signs in with their Marketing Cloud login and asks "Which data extensions can I read in sfmc:main?". They see their data extensions. If it fails, look the message up in the table at the end of this section.
Salesforce's own guides are in Salesforce Help: search for "Marketing Cloud installed packages" and "Web App integration" (the API Integration component).
Add the source (SourceLace admin)
On Connections → Add a source, choose Marketing Cloud (sfmc). Fill in the options with what your Marketing Cloud admin copied (each field has an ⓘ tip).
| Option | Type | Default | Example | What it is |
|---|---|---|---|---|
subdomain |
Text | (required) | mc1a2b3c4d5e6f |
The part of the Authentication Base URI before .auth.marketingcloudapis.com. |
client_id |
Text | (required) | 3k9x2m7q4p1r8t5v6w0y1z2a |
The Client Id of the package's Web App component. |
client_secret |
Secret | (required) | (saved) once saved |
The Client Secret of the same component. Stored encrypted and never shown again. Leave empty to keep the saved one. |
account_id |
Number | (none) | 123456789 |
Optional: the business unit's MID, to sign in to that business unit. |
What people can do
search_schemafinds data extensions, each named by its external key.describe_objectlists its fields and marks the primary key.query(languagesfmc_rest) takes a GET path, optionally with options after?. Only these are allowed: data extension rows (/data/v1/customobjectdata/key/<key>/rowset, such as.../key/Customers/rowset?$pageSize=50&$filter=Tier eq 'Gold'), the data extensions themselves (/data/v1/customobjects), journeys (/interaction/v1/interactions), Content Builder assets (/asset/v1/content/assets), and email and SMS send definitions (/messaging/v1/email/definitions,/messaging/v1/sms/definitions; read only, nothing is sent).get_recordlooks one data extension row up by its primary key value.- Data extension keys with spaces, or punctuation other than
-,_and., are not supported yet.
Using a data extension in a question across systems
A data extension can be one of the tables in a question that combines systems, for example each Salesforce contact next to its subscriber row in Marketing Cloud. Name the data extension by its external key, as in "sfmc:dev"."Subscribers". A data extension whose key has a space or another unusual character cannot be read by SourceLace today. A date is shown as the text Marketing Cloud sends.
When something goes wrong with Marketing Cloud
| What you see | What it means | What to do |
|---|---|---|
| "Marketing Cloud is a pilot and is switched off for your organization." | The pilot has not been switched on for your organization. | Ask your SourceLace contact. |
| "... needs the options 'client_id' and 'client_secret' ..." | The source has no Client Id. | Enter the Client Id and Client Secret from the package's Web App component (step 6). |
| "... needs the option 'client_secret' ..." | A Client Id is set but the secret is empty. | Type the Client Secret into the source (step 6). |
| "Set the Marketing Cloud subdomain for ... (the part before .auth.marketingcloudapis.com)." | The subdomain option is empty or has more than the subdomain. |
Copy only the part of the Authentication Base URI before .auth.marketingcloudapis.com. |
| "The Marketing Cloud account_id for ... must be a number (the MID)." | account_id is not a MID. |
Use the business unit's numeric MID, or leave it empty. |
redirect_uri_mismatch, or "invalid redirect" |
The package's Redirect URI is not exactly SourceLace's. | In the Web App component, set Redirect URIs to the redirect URL at the top of this section (step 3). |
| "Marketing Cloud sign-in failed (invalid_client): ..." | The Client Id or Client Secret on the source does not match the package (a typo, a space, or another package's). | Copy both again from the Web App component (step 6) and save the source. |
| "Marketing Cloud sign-in failed (unauthorized_client): ..." or "... access_denied" | The package is inactive, the person's user may not use it, or the package has no access to that business unit. | Give the package access to the business unit (step 5), and check the person's Marketing Cloud user can log in to it. |
| "Marketing Cloud sign-in failed: ..." (another reason) | Marketing Cloud's own reason follows. | Check the person's Marketing Cloud user has access to the business unit. |
| "Marketing Cloud did not return a valid REST address." | The sign-in answered with an address that is not a Marketing Cloud one. | Check the subdomain is your account's own, then connect again. If it stays, contact support. |
| "Your Marketing Cloud sign-in has expired." or "... session has expired." | The token ended. | SourceLace refreshes it itself. If it then asks, connect again. |
| "That Marketing Cloud endpoint is not on the read allowlist." | Only the read paths listed above are allowed. | Ask for something those paths can read. |
| "Marketing Cloud has no data extension with key ... that you can read." | The key is wrong, or the person cannot see it. | Check the external key with search_schema. |
| "Marketing Cloud: ...: ..." | Marketing Cloud's own message, such as insufficient privileges for a scope. | If it names a permission, tick that Read box on the package (step 4) and connect again. |
| "Marketing Cloud is busy (it asked SourceLace to slow down). Try again in a minute." | Marketing Cloud limits how often one account may ask, and SourceLace asked more often than it allows. | Wait a minute and ask again. If it keeps happening, ask for less data at once, or tell your SourceLace contact. |
| "Marketing Cloud returned HTTP ..." (a number other than 429) | A Marketing Cloud problem. | Try again later; check Salesforce Trust. |
| "Marketing Cloud: no row in ... has ... = '...'." | A lookup by value found no row in that data extension. | Check the value and the data extension's key. |
| "Marketing Cloud returned an unexpected data extension id." | Marketing Cloud's answer was not in the form SourceLace expects. | Try again shortly. If it repeats, contact support. |
| "The data extension changed while it was read (Marketing Cloud's count of its rows changed). Try again." | Rows were added or removed during a long read. | Ask again. |
| "Marketing Cloud sent a different number of rows than it counted in the data extension, so the table cannot be trusted. Try again in a few minutes." | The pages did not add up to the count. | Try again; if it repeats, contact Marketing Cloud support. |
| "Reading this data extension would take more than 5,000 calls to Marketing Cloud (a page holds only N rows because the data extension has many fields, or Marketing Cloud sends no more), so it is not read. Query it on its own with query and a smaller limit instead." | The data extension has so many fields that reading all of it would take more calls than SourceLace allows. | Ask Marketing Cloud on its own with a smaller limit instead. |
| "Marketing Cloud did not return the page asked for, so the rows cannot be read to the end." | Marketing Cloud answered with a different page than requested. | Try again; if it repeats, tell your SourceLace contact. |