Preview CRM Connections
Every PR preview opens with Salesforce (the foo9 dev org) and HubSpot (the "OnRamp CRM - Nonprod" portal) already connected through OnRamp's own CRM broker. No preview holds a Prismatic credential. When a preview's CRM is broken, the cause is almost always one of the shared pieces below, and fixing it fixes every preview at once.
How a preview is connected
| Piece | Where | What it does |
|---|---|---|
| Preview Salesforce app | External Client App "OnRamp Previews", local to foo9 (00DDo000001B9fNMAS) | Its client-credentials flow, run as the user set on the app's policies, is the connection every preview starts with. Connect in a preview consents to it too. Only foo9 users can use it. |
| Preview HubSpot app | Private app defined in infra/hubspot-preview-app/, allowlisted to portal 51740383 | One consented grant on it is the HubSpot connection every preview starts with. HubSpot refuses installs anywhere else. |
| Fleet secrets | SSM /onramp/pr-previews/crm/*, written by the previews stack from infra/app/Pulumi.previews.yaml | Both apps' secrets and the shared HubSpot grant. Only a preview broker's role reads them; anyone who can push a same-repo branch can read them through the preview deploy role, which is why each reaches only the test org and portal. |
| Shared connection | crm-broker/src/crm_broker/shared_connection.py | On a read for vendor 0 whose row holds no credential, the broker copies the shared connection in, checking it reaches the pinned org or portal. |
| Preview database step | devtools/db/preview-crm-fixture.ts, run after migrate | Turns the seed's two connections into OnRamp-owned ones, deletes their Prismatic flow rows and credentials, and turns both self-refresh gates on. |
| Callback relay | https://crm-oauth.preview.onrampapps.com/callback, in infra/app/cf-fn-api-dispatch.js | The one callback both apps register. It redirects to the preview the connect state names, and nowhere else. |
Disconnect and Connect in a preview
- Disconnect removes the connection and makes the broker forget its copy. The shared connection is never ended at the CRM; a grant the preview minted itself through Connect is revoked at Salesforce.
- Connect consents through the relay. For Salesforce choose My Domain
foo9-dev-ed.develop.my.salesforce.com; for HubSpot, portal51740383. - Salesforce forces refresh-token rotation and a 30-day idle expiry on the preview app, so a grant minted in a preview is only ever refreshed by that preview. Salesforce also keeps five approvals per user per app: a foo9 user's sixth Connect across previews retires their oldest preview-minted grant.
- A DB refresh restores the seeded connections; a later read copies the shared connection back in.
When it breaks
| Symptom | Cause | Fix |
|---|---|---|
| Broker error naming a connection that "reaches X, not the pinned Y" | The fleet's grant or app points at another org or portal | Re-mint on the pinned one (below). Never repoint the pin. |
Salesforce reads fail with invalid_client, or invalid_grant on the client-credentials flow | The app's secret changed, or its client-credentials flow or run-as user was switched off | Fix the app in foo9 Setup, then reset its secret (below) |
HubSpot reads fail with BAD_REFRESH_TOKEN | The shared grant was revoked or the app uninstalled from the portal | Re-mint the HubSpot grant (below) |
| Connect lands on a CRM error page about the redirect URI | The relay URL is missing from that app's callbacks | Add https://crm-oauth.preview.onrampapps.com/callback back |
Re-mint the shared HubSpot grant (opens HubSpot's consent page; choose portal 51740383):
AWS_PROFILE=admin bun run crm.preview-fixture-grantReset an app secret (prompts for the value; keys are crmPreviewSalesforceClientSecret and crmPreviewHubspotClientSecret):
cd infra/app && AWS_PROFILE=nonprod-admin PULUMI_BACKEND_URL=s3://onramp-pulumi-state-375255020707 pulumi config set --secret crmPreviewSalesforceClientSecret --stack organization/app/previewsCommit infra/app/Pulumi.previews.yaml; the previews stack applies it to SSM when it lands on main.
What previews cover, and what they don't
Previews review workflow creation against a live CRM: the trigger step's object, field and option pickers, saving, and publishing. Trigger events are deliberately out of scope: inbound delivery is not wired, so those paths fail fast rather than mutating CRM objects from an ephemeral environment.
The seed's two connections
The golden seed still carries vendor 0's Salesforce and HubSpot connections (or_integration 39 and 38) in the shape Prismatic instances gave them, with their Prismatic flow rows. Those instances were deleted with the rest of OnRamp's US Prismatic customers on 2026-10-23 and cannot be revived. Nothing in a preview reads them: the database step converts both rows and deletes the flow rows after every migrate, and the reseed only checks that both rows still exist bound to the pinned org and portal (devtools/db/crm-fixtures.ts).
Looks like this, isn't this
A Salesforce publish can 400 with the connection perfectly healthy: provisioning a Flow needs Metadata API permissions on the user the preview app runs as. The nested Salesforce error never reaches the toast — read the Flask log. That is a foo9 permissions fix.
The "Deploy preview (pipeline)" job failing on execution reaches a terminal state / oversized event is parked in S3 is not this either — that fixture vendor is a separate, third connection behind the integrations-pipeline executor's pre-claim hydrate, not one of the two pinned here. See docs/runbooks/integrations-pipeline-shadow.md's "Known: the preview...smoke check has been red fleet-wide" callout.