Salesforce Admin Guide

What's live in Forge today

Forge brings a modern web UI to Blackthorn on Salesforce. Salesforce remains the system of record; Forge is a faster way to use it. Here's what's wired up today, what's in beta, and what's still on the roadmap.

Architecture overview

Forge is a Next.js application. The browser talks to Forge over HTTPS. Forge talks to your Salesforce org through OAuth-authenticated REST and Composite API calls. Salesforce is the system of record for every customer-facing record.

Forge persists only the tenant's non-PII operational state in Postgres — e.g., tenant rows, sealed OAuth tokens, sessions, audience ID lists, email templates, scheduler jobs, and audit logs. No Salesforce customer record data is ever mirrored to Postgres.

Authentication & sessions

Sign-in uses OAuth 2.0 with PKCE. We never see or store passwords. After Salesforce returns the authorization code, Forge exchanges it for an access token and refresh token, then drops a session cookie called `sid` in the browser.

The session cookie is HttpOnly, SameSite=lax, Secure (in production), and lives for 30 days. The refresh token is sealed with AES-256-GCM and stored in Postgres in `oauth_tokens` (org-level) or `user_tokens` (user-level). Access tokens are short-lived and held only in memory or a Redis cache.

Sponsor and speaker portals use single-use, SHA-256-hashed magic links instead of OAuth. They mint a separate `portal_sid` cookie scoped to the linked record.

Object mapping

Forge does not invent Salesforce object names. On first connection we read your installed sObjects and write a per-tenant `object_mappings` row in Postgres that maps logical keys (Event, Session, Attendee, Form, ...) to the API names actually present in your org.

Allowed namespaces are the Blackthorn managed packages — `conference360__` (Events), `bt_base__` (Base, Forms), `bt_stripe__` (Payments) — plus a small set of standard objects: Account, Contact, Lead, Campaign, CampaignMember, User.

If a logical key has no match in your org we leave it null. Surfaces that depend on it surface a missing-mapping notice; we do not silently fall back to a guess.

Data residency & PII

Salesforce is the system of record for everything customer-facing. Forge's Postgres database holds operational state only — never copies of customer PII.

• Postgres stores tenant rows, sign-in user rows (email + Salesforce user ID), sessions, sealed OAuth tokens, audience snapshot definitions, audience members as ID-only sets, email templates, scheduler jobs, audit logs, portal session metadata, and per-tenant object mappings.
• Redis is an optional just-in-time hydration cache. Attendee and audience data is cached for 2 hours and then evicted. If Redis is unavailable, Forge falls back to a short-lived in-process cache.
• Audience tables intentionally store `sf_id` only — no name, email, phone, or address ever lands there.
• Salesforce is the only durable home for customer PII.

Cache contract

• Salesforce IDs are the primary cache key component for all entries — no cross-tenant data leakage is possible.
• Attendee name and email are cached for up to 2 hours (keys: event-attendees:{tenantId}:{eventId}) as an approved just-in-time hydration shortcut. These entries are auto-evicted and never written to Postgres.
• Most other Redis entries contain only metadata: permission flags, picklist values, FlexiPage layouts, or configuration booleans. Exceptions are documented in the cache audit: SendGrid suppression lists (short-lived, email only) and record lock entries (short-lived, internal user email). See the cache audit document for the full inventory.
• If Redis is unavailable the app degrades to a short-lived in-process cache with the same TTLs. No data is lost or leaked on Redis failure.

Data persistence & PII

How Forge, classic event pages, and Beacon handle your data: what is stored, what is fetched just-in-time from Salesforce, and how long anything is cached. Salesforce remains the system of record; personal data is not persisted outside Salesforce.

How we classify PII

• Personal data (PII): person name, email address, phone number, postal address.
• Not PII: Salesforce record IDs, counts, timestamps, settings and flags, templates, and B2B company (account) names.
• Policy: derive PII just-in-time from Salesforce; persist only IDs and non-PII state. Enforced by convention and automated PII contract tests.

Permissions & sharing

Forge inherits the permissions of the Salesforce user who signed in. We do not bypass Field-Level Security or sharing rules — every read and write goes through the standard Salesforce APIs as that user.

• Make sure the connected user can read and write the Blackthorn objects you expect to use in Forge.
• Set FLS on every custom field you intend to surface in Forge — fields the user cannot see in Salesforce will not appear in Forge either.
• Server-initiated writes go through the managed fflib-based CRUD executor in the Blackthorn package, so they respect the same rules.
• Portal sessions (sponsor, speaker) are scoped to a single record and never inherit broader org access.

MCP

Forge runs a Model Context Protocol (MCP) server so Claude, ChatGPT, Gemini — or any other MCP-compliant client — can read and write your Blackthorn Events data directly, using the connected user's own Salesforce session and permissions. It's the same data your team already sees in Forge; nothing is duplicated into a separate store.

MCP does not provision a tenant on its own. An admin must complete Salesforce connection setup in Forge (see the Setup checklist, Admin → Setup) before the org has anything for an AI assistant to read — the first successful Forge/Salesforce OAuth handshake is what creates the tenant MCP later connects to.

Connect

1. In your assistant's settings, look for Connectors, Integrations, or Custom MCP servers — most clients call this a custom connector.
2. Enter https://forge.blackthorn.io/api/mcp as the server URL.
3. Choose OAuth if it's offered — you'll be sent to a Salesforce login, and signing in is the only consent step. Your assistant never sees or stores your password.
4. If your client doesn't support OAuth for custom connectors, mint a bearer token instead (Settings → API tokens) and paste it into the connector's auth field.

Client-specific notes

• Claude

  1. Recommended: in Claude's connector directory, search for "Blackthorn Beacon" and click Install — no URL to type.
  2. Or manually: in Claude, open Settings → Connectors → Add custom connector.
  3. Claude Code users can install the bundled plugin instead — it wires up the connector and adds workflow skills in one step.

• ChatGPT

  1. Settings → Connectors → enable Developer mode, then Create connector using the URL above.
  2. Choose OAuth as the authentication type. Availability depends on your ChatGPT plan and workspace settings.

• Gemini

  1. Extensions or Connectors settings → Add custom connector, using the URL above.
  2. Choose OAuth. A Google Workspace admin may need to allow custom connectors first.

Tool catalog

Every tool carries one of three scopes — read, write, or delete — enforced by whichever auth method connected the client (OAuth-authenticated user, static bearer token, or session cookie).

Permissions & scope

• MCP inherits the connected user's actual Salesforce permissions — it never bypasses Field-Level Security or sharing rules, same as every other Forge integration (see Permissions & sharing above).
• Three scopes: read (all list/get tools), write (create/update/check-in/schedule), delete (all delete tools). A bearer token can be minted with any subset; an OAuth or session-cookie connection gets read+write+delete.
• Portal-session connections (magic-link attendee/sponsor/speaker access) are restricted to read-only tools scoped to that portal's single event.
• Tenant and user identity are always resolved server-side from the authenticated session — never accepted as a client-supplied parameter.

Security

• OAuth 2.1 with mandatory PKCE (S256) — no long-lived shared secret, refresh tokens rotate on use, and a stolen one-time auth code is unusable without the original client's code_verifier.
• Every tool call is audit-logged (tenant, user, tool name, parameter shape) with PII redacted before it's persisted.
• 60 requests per minute per tenant; responses over 80KB are truncated with a message to paginate or filter instead of silently dumping partial data.
• If the Salesforce connection is broken or rate-limited, every tool returns a structured error with a one-click reconnect link, instead of a generic failure.
• Salesforce access tokens are never included in a tool result — sealed and cached server-side only.

Sample things to ask

• “What events do we have coming up in the next 30 days?”
• “Give me a dashboard summary — attendees, revenue, and email performance across all our events.”
• “Create a test session called "QA Walkthrough" on [event] from 2–3pm.”
• “Check in [attendee name] for [event].”
• “What's the open rate on our last campaign?”
• “Delete the test session I just made.”

See it in action

• 

  Dashboard

  “Give me a dashboard summary across all our events.”

• 

  Event metrics

  “What's the capacity and registration funnel for this event?”

• 

  Email performance

  “What's the open rate on our last campaign?”

• 

  Attendee check-in

  “Check in this attendee for the event.”

Salesforce platform features

Forge writes through standard Salesforce REST and Composite APIs as the signed-in user. That means every platform feature your admin has configured runs the same way it does in Salesforce itself — Forge does not bypass anything.

• Validation rules: Run on every save. If a rule fails, Forge surfaces the error inline next to the offending field, with the field's label resolved from describe metadata.
• Record types: When a surface supplies a RecordTypeId, Forge writes it. Page layouts per record type are honoured when the layout describe is fetched.
• Apex triggers, Process Builder, and Flows: Execute server-side automatically because Forge writes through standard APIs. Their errors propagate to the user the same way validation errors do.
• Field-Level Security: Reads honour FLS automatically — fields the user can't see in Salesforce don't appear in Forge. Writes that violate FLS surface a Salesforce error; some layouts also pre-filter to writable fields based on describe metadata before rendering.
• Sharing rules and record-level access: Implicit. Forge calls Salesforce as the signed-in user, so any record the user can't access in Salesforce is invisible to Forge too.
• Permission sets and profiles: Enforced by Salesforce on every API call. Forge has no separate authorisation layer to bypass them.
• Server-initiated writes: Routed through the managed fflib-based CRUD executor in the Blackthorn package, which respects the same rules.
• Org locale, currency, and timezone: Forge uses its own locale cookie for UI strings. Org-level currency, locale, and timezone defaults are not yet auto-applied — this is a known gap, not a design choice.

Sync, caching & background jobs

• When you sign in, Forge refreshes your organization's most active Salesforce data in the background — events, sessions, tickets, registration forms, sponsors, speakers, and attendees typically update within a few minutes.
• Less frequently changing data — such as rooms, tracks, keywords, translations, and fundraising records like auctions, donations, and pledges — refreshes on a longer cycle and can take up to a few hours to catch up.
• Email send schedules are handed off to the Smart Scheduler service, which calls back into Forge to deliver each batch.
• Internal cron endpoints under `/api/cron/*` run housekeeping — for example, pruning login events older than 90 days.
• If something you just changed in Salesforce doesn't appear in Forge right away, wait a few minutes and refresh the page — for less frequently updated data, give it a few hours before contacting support.
• Redis cache reads and writes are wrapped in try/catch; the app degrades to in-memory caching if Redis is unavailable.

Troubleshooting