Salesforce Integration

Salesforce is the system of record for customers, contacts, products, pricebooks, opportunities, field surveys, and proposal attachments. The inspection app is an operational layer around that data because field users need a faster, guided interface while the company still needs Salesforce to remain authoritative for customers, catalog products, opportunity records, proposal attachments, and traceable identifiers.

Objects used

Salesforce object	App usage
Account	Customer lookup, shipping/billing address, division/branch context
Contact	User provisioning and role metadata; the inspecting tech on a Field Survey
Product2	Catalog item target for inspection mappings
Pricebook2	Division/customer pricebook selection
PricebookEntry	Active price and product availability
Opportunity	Submitted inspection and expert proposal container
OpportunityLineItem	Proposal line items
ContentVersion	PDF/DOCX/report attachment upload
Field_Surveys__c	Renovation Review (Field) survey created on completion

Data flow


Contact role fields ── provision ── app user access
Account and Opportunity ── provide ── customer and proposal context
Product2 plus PricebookEntry ── provide ── mapped item availability and price
Generated proposal file ── uploads as ── Salesforce ContentVersion
Completed field review ── creates ── Field_Surveys__c record

Authentication

The working production authentication path is SOAP login, and it is the deliberate default. It is chosen because it reliably has the object and field access the app needs. OAuth client-credentials is used OAuth-first for specific reads where the integration user is permissioned — notably SaleID reads — and falls back to SOAP when OAuth cannot authenticate or cannot read a field.

Setting the auth mode to OAuth does not force OAuth everywhere. Unless client-credentials is enabled org-side with full integration-user permissions, OAuth silently falls back to SOAP. Do not assume a green OAuth path masks a missing integration-user permission — capture enough detail to tell the two apart.

SaleID behavior

SaleID is generated by Salesforce after Opportunity creation. Proposal generation therefore reads the Opportunity after submission and waits briefly for Opportunity.SaleID__c to appear. The current safe pattern is OAuth-first for SaleID-sensitive reads with SOAP fallback.

Field Surveys

Completing a Renovation Review (Field) can create a Salesforce Field Survey (Field_Surveys__c) automatically. The record uses the Renovation Inspection record type and captures:

the Account the renovation belongs to;
the body of water that was reviewed;
the inspecting tech (as the submitting Contact);
a link back to the completed review.

This replaces the older pattern of a separate supervisor review and manual hand-off — the survey is created the moment any user marks the review complete. The push is controlled by an environment flag (FIELD_SURVEY_PUSH_ENABLED) and is off by default, so it is enabled against the sandbox on Preview before production.

Account cache

The customer and Body-of-Water pickers on a new inspection can be served from a Postgres read model — a local copy of the relevant Salesforce Accounts and Bodies of Water refreshed on a schedule (twice daily) by a cron job. This makes the pickers open instantly instead of waiting on live Salesforce.

The cache is optional and off by default. It must be seeded before it is switched on, and the picker routes refuse the cache path until a sync has succeeded — a cold cache falls back to live Salesforce rather than showing an empty list.

Site Evaluation photo import

For Job Documentation, the app can import existing Salesforce Site Evaluation photos on demand. Because that pulls files through the Salesforce API, the import is guarded with a per-run file cap and a reserve against the daily request budget, and it stops gracefully rather than exhausting the org’s quota.

Audited writes

Every Salesforce write the app makes is recorded in the Audit Log before and after the write, with automatic reconciliation of operations that were interrupted mid-flight. The Salesforce records stay authoritative; the audit trail records what the app did to them.

Pitfalls

Do not assume a Salesforce field exists immediately after Opportunity creation if Salesforce automation populates it asynchronously.
Do not use Standard Price Book behavior when the requirement is division-specific or customer-specific pricebook behavior.
Do not silently ignore OAuth permission failures; SOAP fallback can mask a missing integration-user permission.
Do not enable the account cache before seeding it, and do not expect the Field Survey push to write records in an environment where its flag is off.
Remember the sandbox is a partial copy: field availability and flows can differ from production, so verify Salesforce-schema features against production.

Admin Tools explains how mappings, pricebooks, routing, and the account cache are maintained.
Renovation Review (Field) is the flow that creates Field Surveys.
Audit Log records the Salesforce writes described here.
Deployments explains why preview and production Salesforce environments must stay distinct.