Setup
How to connect the Agent Platform's Salesforce package to your organization on Flourish after installing it, and how to let agents work with your Salesforce records.
Overview
Setup is two jobs, done once by an admin:
- Create the configuration record. It tells the package which organization it belongs to on Flourish. Every part of the package needs it: the Agent Builder, the Chatbot, the Web App component, My Access and the Flow action.
- Connect your Salesforce org to Flourish. Only the Salesforce tools need this: Salesforce Data, Salesforce Describe and Salesforce System. Building agents, chatting with them and calling them from a Flow all work without it, so this can wait until an agent needs your records.
Flourish gives you what the first job needs during onboarding: your organization's name on Flourish and its token. Ask your Flourish contact if you do not have them.
The configuration record
The package reads its settings from a custom metadata type called Flourish Intelligence Setting, from a single record named global.
- In Setup > Custom Metadata Types, click Manage Records beside Flourish Intelligence Setting.
- Click New, and set both the Label and the Flourish Intelligence Setting Name to
global, in lower case. The name is what the package looks the record up by, so it has to be exactly that. - Fill in the three fields below and save.
| Field | Holds |
|---|---|
| FL API Org | Your organization's name on Flourish. |
| FL API Token | Your organization's token. |
| FL API Env | A name for this Salesforce org: prod in production, and a name of its own, such as sandbox, in a sandbox. It decides which Salesforce org the Salesforce tools work in. See Which org an agent works in. |
Leave the other fields blank. Connected App: Client ID, Connected App: Client Secret, Connected App: Refresh Token and Chatbot Embed Site are still on the record, but nothing in the package reads them.
The token acts as your organization. Anyone who has it can build, change and run your agents, and spend against your monthly limit, so treat it like a password.
Connecting your Salesforce org
The Salesforce tools work in your org through credentials Flourish holds for it. They do not act as the person chatting. Every call runs as one Salesforce user you choose, through an External Client App in your org that uses the OAuth client credentials flow. Flourish keeps three values from it, the consumer key, the consumer secret and your org's My Domain URL, under your organization's name and an environment name.
Until Flourish holds them, an agent with a Salesforce tool turned on cannot reach your org, and says so when it tries. The Agent Builder in Salesforce gives no warning beforehand.
If Flourish Core is installed
Flourish Core's Admin Hub creates the app, tests it, and sends the three values to Flourish without you leaving the page. Follow Connecting the org to Flourish on Flourish Core's Setup page.
- The app runs as whoever creates it, so sign in as the user the agents should act as before you start.
- On the last step, check the Environment. It has to match FL API Env on your Flourish Intelligence Setting record.
Without Flourish Core
- In Setup > External Client App Manager, click New External Client App. Give it a name and a contact email, and leave Distribution State at Local.
- Under API (Enable OAuth Settings), check Enable OAuth. Enter any HTTPS address as the Callback URL: this flow never uses it, but the form asks for one. Add the Manage user data via APIs (api) scope, check Enable Client Credentials Flow, and create the app.
- On the app's Policies tab, click Edit. Under OAuth Policies, check Enable Client Credentials Flow and enter the Run As (Username). Set IP Relaxation to Relax IP restrictions, since Flourish calls from addresses your login IP ranges cannot anticipate. Save.
- On the Settings tab, open OAuth Settings and click Consumer Key and Secret to reveal them.
- Give your Flourish contact the consumer key, the consumer secret, your org's My Domain URL (the
https://yourdomain.my.salesforce.comaddress, with nothing after it) and the FL API Env name from your record.
The user the tools run as
That user decides what agents can reach. Every call runs with their permissions and record access. Salesforce Data is held to both that user's access and the agent's access grants; Salesforce System can do anything that user can. A dedicated integration user with API access is the safest choice.
Keep that user active. If it is deactivated or loses access, the Salesforce tools start failing, and nothing in Salesforce warns you.
Integrations are separate
Add Integration, on an agent's Advanced tab, connects an account for the agent's own scripts, acting as whoever connected it. The Salesforce tools never use it, and it needs none of this setup. See Integrations.
Which org an agent works in
Your token belongs to your organization on Flourish, and each Salesforce org you connect is filed under an environment name. One organization can have production connected as prod and a sandbox as sandbox. Which one an agent works in depends on where the conversation started:
| Started from | Works in the org connected as |
|---|---|
| The Agent Builder's Preview, the Chatbot, the Web App component or the Flow action | The FL API Env on that Salesforce org's record |
| Greenhouse, a chat window on your website, or a link | prod |
| A Daemon call over HTTP | The environment in its fl-api-env header |
So an agent people reach outside Salesforce works in the org connected as prod, whichever org it was built in.
Sandboxes
A sandbox made from production copies the record, prod included. Until you change it, agents in the sandbox work in your production org's records. In the sandbox, set FL API Env to a name of its own, such as sandbox, and connect the sandbox under that name.
A sandbox lists the same agents as production. Agents belong to your organization on Flourish, not to a Salesforce org, so the Agent Builder in a sandbox opens your live agents, and a change saved there changes them. Try a change on a new version, and deploy it only when it is ready.
Checking it works
- Open the Flourish Agent Builder tab. The home screen lists your organization's agents, or none if nobody has built one yet. An error saying the
globalrecord was not found means the record is missing or its name is not exactlyglobal. One reading Agent Platform returned 401 means FL API Org or FL API Token is wrong. - Ask an agent about your records. On an agent whose deployed version has Salesforce Data with a read grant, or Salesforce System, open Preview and ask something only your org can answer, such as how many Accounts it holds. If it says it cannot reach Salesforce, your org is not connected under the environment on the record.