Salesforce

Source module: app/connectors/salesforce.py. Kind: facts only. Display name: "Salesforce".

Purpose

Reads Case status history and Opportunity stage history through the REST/SOQL API so that resolution-type claims (from Agentforce exports or any vendor) and lead/opportunity outcomes can be checked against the CRM.

Auth and scopes

Item	Value
Method	Connected app access token, sent as Authorization: Bearer, against the org's instance_url; API version v60.0
Credentials stored (encrypted)	instance_url, access_token
Least-privilege scopes	OAuth scope api (read). Assign a profile or permission set with read on Case, CaseHistory, Opportunity, OpportunityHistory, OpportunityContactRole, and field-level read on Contact.Email. No create/edit/delete permissions.
Connection test	GET /services/data/v60.0/limits (remaining daily API requests recorded in health)
Non-secret config	none

Fields pulled and why

SOQL	Fields	Used for
Case WHERE LastModifiedDate > :since	Id, Status, CreatedDate, ClosedDate, Origin, Contact.Email, LastModifiedDate	Subject id, channel (Origin), hashed contact email, watermark
CaseHistory WHERE CaseId = :id AND Field = 'Status'	OldValue, NewValue, CreatedDate	Status-change and reopen facts
Opportunity WHERE LastModifiedDate > :since with subqueries OpportunityHistories and OpportunityContactRoles WHERE IsPrimary = true LIMIT 1	Id, StageName, CloseDate, LastModifiedDate; history StageName, CreatedDate; the primary contact role's Contact.Email	Opportunity-stage facts, hashed contact email. Opportunity itself has no Contact lookup; the primary contact role is the customer.

What is hashed / never stored

• Contact.Email (the Case contact; the Opportunity's primary contact role) → customer_hid (HMAC-SHA256, per-tenant key); the email is discarded. An opportunity with no primary contact role carries no customer_hid.
• Case subject, description, comments, feed items, contact names/phones, and any other field are neither queried nor stored.
• The access token is stored only as ciphertext.

Incremental sync and watermark

• Both queries filter on LastModifiedDate > <watermark> (ISO-8601, 1970-01-01T00:00:00Z on first sync). SOQL pagination follows nextRecordsUrl until done.
• One CaseHistory query is issued per modified case.
• Watermark = maximum Case LastModifiedDate seen (opportunity timestamps do not advance it).
• Upserts are idempotent; re-syncing a record refreshes its facts.

Rate-limit handling

Shared HttpClient (Retry-After, exponential backoff on 429/5xx, 6 attempts, immediate reauth failure on 401/403). Salesforce enforces a daily API request allocation; test_connection reports the remaining count so an admin can size backfills.

Fact types produced

fact_type	Subject / kind	When	Attributes	raw_ref
status_change	sf_case_{Id} / ticket	Each CaseHistory row for Status	from, to (lower-cased), actor: "agent", customer_hid, channel: <Origin>	salesforce:casehistory:{Id}:{i}
reopen	sf_case_{Id} / ticket	A status history row moving from closed to any other status	customer_hid, channel	salesforce:casehistory:{Id}:{i}:reopen
opportunity_stage	sf_opp_{Id} / opportunity	Each OpportunityHistory row	stage: <StageName>, customer_hid	salesforce:opphistory:{Id}:{i}

Claims produced

None. Salesforce Agentforce usage/claims are not exported by this connector; supply them via CSV upload mapped to salesforce_agentforce_conversation (or another contract), using subject ids that match the fact subject ids above or that resolve through identity links.

Subject id format

sf_case_{CaseId} and sf_opp_{OpportunityId} (15/18-character Salesforce ids as returned by the API).

Known limitations

• No customer_message, human_reply, escalation or csat_response facts. Case comments, email messages and owner changes are not read. The salesforce_agentforce_conversation vendor lens (customer_message_within) therefore cannot be satisfied from this connector alone; conversation facts must come from a help-desk connector or a CSV upload linked by hashed email.
• Case Origin is used as the channel verbatim (e.g. Web, Phone, Email); contract exclusions match case-insensitively.
• Reopen detection only considers the literal closed status; orgs with custom closed statuses need a CSV mapping or a contract tweak.
• One history query per case (N+1); large backfills consume API allocation.
• Access tokens expire; the connector does not refresh them. Re-authenticate with a new token when reauth is reported, or use a long-lived integration user token.