A Salesforce call note should preserve what happened. An opportunity update should express what the team decided. Keep those artifacts linked, but never collapse them into one unreviewed write.
Salesforce gives teams many ways to store notes, activities, files, and opportunity fields. That configurability means there is no safe universal payload. A production workflow begins by reading the target org's metadata and ownership rules, not by copying a template from another org.
Choose the Salesforce destination before writing
Decide where narrative evidence belongs, how it links to the opportunity, account, and contacts, who can view it, and how it appears in the rep's normal workflow. Salesforce's enhanced notes use content-related objects, and sharing behavior is part of the implementation. Validate the chosen model in a sandbox.
Use a destination contract with object type, record ID, association method, visibility, owner, timestamp semantics, and retention policy. If a call maps to two open opportunities, the contract should return “review required,” not choose the most recent record.
Inspect the target org, not a generic schema
Inventory enabled note and activity models, custom fields, record types, validation rules, sharing, required contact roles, automation, and integration-user permissions. Record the API names as well as visible labels. A renamed label may look familiar while pointing to a different configured meaning.
Decide how the note should appear to a rep, manager, and future account owner. A technically created note that the intended reader cannot find or view is not a successful write.
Separate narrative evidence from opportunity fields
| Artifact | Contains | Write rule |
|---|---|---|
| Narrative note | Problems, constraints, objections, commitments, provenance | Rep reviews attribution and accuracy |
| Next activity | Action, owner, due date | Requires an explicit commitment or team rule |
| Opportunity stage | Configured buying milestone | Only permitted transition with evidence |
| Close date | Expected commercial decision date | Buyer-backed timeline; never meeting date alone |
This separation makes partial approval possible. The note may be accurate even when the proposed stage is wrong. Rejecting one should not discard the other.
Preserve source and interpretation separately
For important statements, retain the speaker, source timestamp, and confidence in the review packet. The visible Salesforce note can remain concise, but it should link to permitted provenance or identify the source call. Mark normalized values—such as a date converted to the org's expected format—as derived.
Do not place generated confidence scores into business fields unless the organization has defined how they are produced and consumed. Confidence should control review and suppression, not masquerade as opportunity probability.
Define field authority and transitions
For each writeable field, document the API name, data type, source of truth, allowed values, permitted transitions, null behavior, reviewer, conflict rule, and rollback method. Salesforce's developer guidance notes that update requests require exact API field names and that an unknown field causes an error.
Do not equate technical permission with editorial or business authority. An integration user may be allowed to write Amount; the sales organization may still prohibit generated changes to Amount.
Define the behavior of blank and invalid values
Document whether an empty source means “unknown,” “not discussed,” or “clear the CRM value.” Default to no change. Clearing a field needs its own evidence and approval. For picklists, validate against the target record type; for dates, preserve source timezone and avoid inferring a close date from the next meeting.
Set transition rules for stage and status fields. A replayed older call must not move an opportunity backward or reopen a closed record. Suppress suggestions when the destination is closed, locked, owned by another workflow, or newer than the evidence.
Record field-level receipts
For each proposed field, store the object and record ID, API field name, snapshot value, proposed value, evidence, contract version, reviewer, request result, and verified readback. Note creation gets a separate receipt with its content hash and association IDs.
Build the reviewed writeback sequence
- Capture call identity and transcript provenance.
- Resolve contacts, account, opportunity, owner, and record access.
- Read the relevant Salesforce metadata and current field values.
- Draft the narrative note and independent field suggestions.
- Present old value, proposed value, evidence, and reviewer controls.
- Re-read current values, reject stale suggestions, write accepted outputs, and verify.
If the reviewer changes the opportunity or contact association, invalidate the earlier permission, duplicate, and field checks. Re-run them against the new destination before enabling approval.
Recover from uncertain writes
Timeout after a request does not prove failure. Read the destination and compare the expected value or created note receipt. If the note exists, record success; if the field already holds the approved value, do not send another write. If state differs and a human edited it, create a conflict rather than forcing the proposal.
Test the target Salesforce org
Use a sandbox to test custom picklists, renamed labels, required validation rules, restricted fields, private notes, inactive owners, multiple opportunities, contact roles, concurrent edits, token expiry, timeout after commit, duplicate webhook delivery, and partial success. A passing test asserts the final record and audit receipt, not merely an HTTP response.
Also test a user who can read the opportunity but not the note, and one who can approve the note but cannot change the stage. Permission boundaries should produce a visible, recoverable state.
Add tests for multiple record types, custom validation rules, a stage picklist changed after proposal, restricted contact visibility, duplicate call delivery, a note created without its intended association, a concurrent Flow update, and rollback after a manager edit. Assert the final Salesforce records and sharing state.
Release only with an operator runbook
- How to identify a wrong destination and relink or remove the note.
- How to reconcile a timeout or partial field update.
- How to pause one field while leaving note capture active.
- How to inspect the contract and source used for a proposal.
- How to roll back without overwriting a newer human edit.
Where Gangly fits
Gangly's Post-Call Notes documentation describes rep-reviewed notes and one-click Salesforce opportunity sync. Repository integration facts say initial setup requires Salesforce admin access. Confirm edition prerequisites, custom mappings, sharing, validation rules, and current plan terms in the target org.