Salesforce v2 — two-way Case sync, agent/queue mapping, `ticket-updated` trigger

Point-in-time planning artifact. What shipped names the trigger Session Updated (session-updated, not ticket-updated); the attribute prefixes stayed sf_case_ / sf_contact_ / sf_<object>_. The shipped contract is documented in docs/integrations/salesforce/email-cases.mdx.

Consolidated design for ONE minimal PR replacing #2229 (case field sync), #2223 (agent parity), and the sync-related half of the intent behind #2227. Scope is strictly TicketingSystemEnum.SALESFORCE_V_2 (salesforce_v2); v1 (salesforce, MoneyGram MIAW + legacy email-to-case) is untouched. Baseline: origin/main @ 14b7ab598f. Every claim below cites the file it was verified against.

1. Goal

SF → OpenCX freshness. A Salesforce agent edits any Case field → the linked session’s sf_case_* attributes refresh within seconds (today they refresh only on new_case / new_reply / human_agent_comment / owner_changed — backend/src/salesforce-case-integration/salesforce-case.service.ts:786,1432,2396,2475).
OpenCX → SF write-back. A session attribute that maps to a Case field changes on our side (workflow “Update Session Attributes”, inbox agent edit) → the Case field updates.
A workflow trigger that fires on those attribute changes so agentic workflows can act on a Salesforce Case change. No such trigger exists today (backend/src/workflow/enums/workflow-trigger.enum.ts has no session/ticket “updated” member).
Agent mapping + assignee sync. Case.OwnerId ↔ chat_sessions.assignee_id, both directions, behind the existing chatbots.sync_assignee_from_3rd_party / sync_assignee_to_3rd_party flags (backend/src/db/opencx.ts:1530-1531) — which gate nothing for Salesforce today (backend/src/chat/chat-integration.service.ts:220).
Queue → team mapping. A Case owned by a Salesforce Queue (00G…) lands the session in the mapped OpenCX team.

2. Non-goals (explicitly deferred)

Polling / reconciliation worker for Case fields (webhook-first; see §10 for the poll follow-up).
Attributing SF agent comments/emails to OpenCX teammates with avatars (the identity half of #2223).
Outbound team → Queue push (Zendesk v2 has no outbound group push either — backend/src/zendesk-integration-v2/zendesk-group-mapping.service.ts:17-24).
Roster cache table + dashboard mapping UI for agents/queues (Zendesk has zendesk_agents + PUT /agents/mapping; phase 1 here is auto-map-by-email with a persisted link, no UI).
Firing ticket-updated for editable_custom_data edits (the ticket payload exposes only custom_data — backend/src/workflow/definitions/payloads/workflow-trigger-payload.utils.ts:111).
case_closed refreshing fields / firing ticket-resolved (raw update at salesforce-case.service.ts:2481-2531; separate fix).
“For Each Matching Session” cron action bundled into #2229 — its own PR.
“Scan Salesforce Case Queue” action (#2227) — read-only bulk read, independent; keep as its own PR.

3. What exists on `main` (facts the design leans on)

Building block	Where	Reuse
Case snapshot → `chat_sessions.custom_data` under `sf_case_*` (all readable, non-compound, non-system fields) + contact + configured related objects, then AI-context-filtered diff → `salesforce_fields_updated` chat_history row	`SalesforceCaseService.syncSalesforceFieldsToCustomData` `salesforce-case.service.ts:2629-2758`; `notifyAllowedFieldsChanged` `:2779-2828`	The inbound refresh; call it from the new event
Central session custom-data write with integration reflection (Intercom/HubSpot only)	`chatSession_repo_mergeCustomData` `backend/src/chat-session/repo/merge-custom-data.ts:7-115` (reflect branch `:79-110`)	Add `salesforce_v2` reflect arm + fire trigger + `keysToClear`
Agent-edited bag write with HubSpot diff push	`chatSession_service_updateCustomData` `backend/src/chat-session/service/update-custom-data.ts:59-80`	Add `salesforce_v2` arm
Contact-side precedent: repo fires `contact-updated` behind a value diff, supports `keysToClear`	`backend/src/consumer/repo/merge-custom-data.ts:55-130`, `emit-contact-updated.ts`	Mirror 1:1 for sessions
Trigger definition template with `changedFields`	`backend/src/workflow/definitions/triggers/contact-updated.trigger.ts`	Template for `ticket-updated`
Ticket payload already carries `customData` (= `custom_data`)	`ticket.payload.ts:138-144`, `workflow-trigger-payload.utils.ts:111`	`{{trigger.ticket.customData.sf_case_Status}}` works out of the box
Assignee mirror chokepoint + per-integration dispatcher	`mirror-assignee-to-integration.ts:17-37` → `ChatIntegrationService.syncAssigneeToThirdParty` `chat-integration.service.ts:167-241` (`SALESFORCE_V_2` no-op at `:220`)	Add the `SALESFORCE_V_2` arm
Zendesk v2 assignee sync (the simplest shipped shape: one consume-once Redis key, `changeAssignee` no-op guard as primary safety, `actor: {type:'integration'}`)	`backend/src/zendesk-integration-v2/zendesk-assignee-sync.service.ts`	Copy the shape
Zendesk v2 queue→team inbound: `assignToTeam({shallowAssignment:true, actor:{type:'integration'}, trigger:'integration'})`	`zendesk-group-mapping.service.ts:225-236`	Same call
Per-membership external ids	`chatbot_users.hubspot_user_id` / `zendesk_user_id` `opencx.ts:1552-1562`	Add `salesforce_user_id`
Queue registry with CRUD (API-only, no dashboard UI)	`salesforce_escalation_teams` (`org_id, team_name, salesforce_queue_id, enabled`) `opencx.ts:4132-4141`; `salesforce-escalation-teams.{service,controller}.ts`	Add nullable `group_id` FK
Existing SF echo-guard convention (consume-once Redis key)	`salesforce_v2:case:webhooks:ignore:{caseId}` `salesforce-case.service.ts:2593-2610`	Same key style for owner echo
Per-key lock util	`backend/src/utils/redis-lock.ts` (`acquire/release/waitForRelease`)	Serialize refreshes per case
Existing SDK writes	`SalesforceCaseSDK.updateCase` `salesforce-case-sdk.ts:583-596`, `updateCaseOwner` `:606-613`, `describeUpdateableCaseFields` `:1089-1110`, `getCurrentUser` `:1112-1121`	No new SDK surface except `getUserById` / `findActiveUsersByEmail`
Webhook contract: `POST /backend/salesforce-case/webhook/:token?` with `?caseId=&type=` (token in `x-opencx-token`)	`salesforce-case.controller.ts:80-157`; event enum `dto/salesforce-case-webhook.dto.ts:3-10`	Add ONE new `type` value, same shape

4. Assessment of the open PRs

PR	Verdict	Keep	Drop / why
#2229 case field sync (+5.5k)	Right problem, oversized solution	Namespace replacement semantics (a field nulled in SF must clear locally — today `serializeSalesforceRecordForCustomData` drops nulls so stale values linger `salesforce-case.service.ts:152-169`); diff includes removed keys; per-case lock	New JSON body contract `{event_type:'case_changed', caseIds[]}` + Apex `Queueable`+`Finalizer` (customers already have the query-param contract; one more `type=` is additive), sObject-collections bulk path, 200-batch endpoint, custom `replace-salesforce-case-custom-data.ts` repo helper (the contact repo’s `keysToClear` idiom does the same inside the existing merge), the whole “For Each Matching Session” bundle, no workflow trigger emitted (only a socket event)
#2223 agent parity (+1.9k)	Right shape, over-guarded	`chatbot_users.salesforce_user_id` + partial unique index; email auto-link persisted NULL-only; outbound `SALESFORCE_V_2` arm in `syncAssigneeToThirdParty`; inbound owner→assignee on `owner_changed` gated on `sync_assignee_from_3rd_party`; AI ↔ integration user; Queue (`00G`) → team; relaxing the `HANDED_OFF` early-return only when sync-from is on	150-line Lua guard with legacy/shadow keys (HubSpot/Zendesk use one consume-once `SET … EX 15` key each); `mirrorAssigneeToIntegration` param threaded through `changeAssignee`/`assignSessionToAi` (Zendesk pattern arms a consume-once key instead — no signature change); teammate identity/avatar attribution on inbound comments/emails; queue mapping by `team_name == groups.name` string match (a nullable FK is explicit and cheaper to reason about); `LastModifiedById` SOQL widening; CaseComment Apex trigger docs
#2227 queue scan (+5k)	Different feature (read-only bulk read for workflows)	—	Not sync. Leave as its own PR; not part of this consolidation

5. Design

Four pieces, one PR, four commits (§9). Every hook point is inside a SALESFORCE_V_2-gated arm or inside backend/src/salesforce-case-integration/.

5A. `ticket-updated` workflow trigger (generic, fired from the session custom-data seam)

Definition — backend/src/workflow/definitions/triggers/ticket-updated.trigger.ts, WorkflowTriggerEnum.TICKET_UPDATED = 'ticket-updated', registered in triggers/index.ts. Payload:

ticket:         ticketPayload            // current snapshot; customData = chat_sessions.custom_data
changedFields:  Text[]                   // custom_data KEYS that changed, e.g. ["sf_case_Status"]
previousValues: AnyObject                // { key: old value } for the changed keys (absent key = was unset)

No trigger_configuration (like contact-updated); authors gate with an if-block on changedFields contains "sf_case_Status" (array contains exists in the condition evaluator) and/or previousValues.sf_case_Status. Description states: fires when a ticket’s attributes change (integration sync, workflow “Update Session Attributes”, API); status/assignee/team/tag changes have their own triggers; a workflow that writes attributes to the same ticket re-triggers itself → gate on Changed Fields (same wording as contact-updated.trigger.ts:36-38). Fire site — exactly one: inside chatSession_repo_mergeCustomData (merge-custom-data.ts), mirroring consumer/repo/merge-custom-data.ts:55-92:

read prior custom_data (one SELECT — the contact repo already pays this),
merge (COALESCE(custom_data,'{}') || $set, then - $keysToClear::text[] when keysToClear is non-empty — new optional param, same idiom as the contact repo),
changedFields = keys where JSON(prior[k]) !== JSON(merged[k]) ∪ cleared keys; if empty → no fire,
workflowTrigger_service_triggerByType({ orgId, triggerPayload: ticketUpdatedTrigger.$trigger({ ticket: await getTicketPayload({sessionId}), changedFields, previousValues }) }), wrapped in try/catch + console.error — never fails the write (mirrors emit-contact-updated.ts).

Because the Salesforce refresh (5B) writes through this same function, it needs no fire site of its own. Loop termination = the diff: a workflow that writes the same value again produces changedFields = [] → no fire. Dashboard: trigger types are SDK-generated only (dashboard/packages/sdk/src/schema.ts), so pnpm gensdk is the only dashboard change.

5B. Inbound freshness — `type=case_updated` webhook

DTO/enum: add case_updated to SalesforceCaseEventType (dto/salesforce-case-webhook.dto.ts:3-10); mapApexTypeToEventType passes it through (salesforce-case.controller.ts:36-58). Same query-param contract as every existing event.
Dispatch: case 'case_updated' in dispatchWebhook (salesforce-case.service.ts:244-330) → handleCaseUpdated(orgId, caseId) fire-and-forget in prod, awaited otherwise (identical to owner_changed).
Handler handleCaseUpdated: status-blind session lookup by (copilot_id, salesforce_case_id); unknown case → log + return; acquire RedisLock salesforce_v2:case:fields-refresh:{orgId}:{caseId} (waitForRelease if held — a later webhook must not be dropped, it may carry the newest state); call the existing syncSalesforceFieldsToCustomData({ orgId, sessionId, caseId, notifyOnFieldChange: true }); release.
Stale-key clearing (the one behavioural change to the existing refresh): in syncSalesforceFieldsToCustomData, compute keysToClear = priorKeys.filter(k => k.startsWith('sf_case_') && !(k in caseCustomData)) and pass it to chatSession_repo_mergeCustomData. Applies to every caller (new_case/new_reply/…): a Case field cleared in Salesforce now clears locally instead of lingering. Same for sf_contact_* on the contact merge (already supported by the contact repo’s keysToClear).
notifyAllowedFieldsChanged: iterate the union of before/after keys so a removed whitelisted key is reported as {old, new: null} (cherry-pick of #2229’s small change at its :3036-3050).
Emits nothing else — the ticket-updated fire happens inside the merge (5A); the salesforce_fields_updated chat_history row keeps working unchanged.
Docs (docs/integrations/salesforce/email-cases.mdx): one new Apex method sendCaseUpdatedEvents(List<Id>) (clone of sendCaseOwnerChangedEvents with &type=case_updated) and trigger 7. Case trigger (any field change) — after update, fires for every record in Trigger.new (no field filter; the backend diff dedupes). Documented as optional-but-recommended; existing 6 triggers unchanged; existing customers keep working with zero changes. Add the trigger to the Apex test class. Note the ceiling: each Case update = one @future callout, including echoes of OpenCX’s own writes (harmless: no diff → no trigger).

5C. Outbound write-back — attribute → Case field

New SalesforceCaseService.syncCustomDataToCase({ orgId, sessionId, changed }) (in salesforce-case.service.ts, next to syncSalesforceFieldsToCustomData):

session must have salesforce_case_id; org must be salesforce_v2 (callers already gate on ticketing system, re-check anyway).
describeUpdateableCaseFields(orgId) → set of updateable API names (existing SDK method, salesforce-case-sdk.ts:1089-1110).
For each [key, value] in changed: field = key.startsWith('sf_case_') ? key.slice(8) : key; keep only if field is updateable and field !== 'OwnerId' (owner is owned by 5D) — one rule for both bags. Coerce boolean/number/currency exactly as update-salesforce-case.action.ts:184-219 does (reuse that mapping inline).
Nothing left → return. Else ONE SalesforceCaseSDK.updateCase(orgId, caseId, fields); on error console.error (never throws into the caller — mirrors HubSpot sync-custom-data-with-ticketing-system.ts:190-203).
No echo guard needed for fields: the SF case_updated echo re-fetches the Case; local custom_data already holds the value (merged before the push) → changedFields = [] → nothing fires. (// ponytail: a concurrent local edit between push and echo could be overwritten by the echo snapshot; self-heals on the next change.)

Wire-up (both mirror the existing HubSpot arms, keyed on chatSessionTags_service_getTicketingSystem(orgId) === 'salesforce_v2', so v1 never enters):

chatSession_repo_mergeCustomData reflect branch (merge-custom-data.ts:93-109): else if (ticketingSystem === 'salesforce_v2') await SalesforceCaseService.syncCustomDataToCase({…, changed: <only the changedFields subset>}) — lazy import like the HubSpot one. Callers reaching this with reflectOnIntegration default-true on an SF org: the workflow “Update Session Attributes” action (merge-ticket-custom-data.action.ts:108). Every SF-internal merge passes reflectOnIntegration:false (salesforce-case.service.ts:2664, :2911) → no self-push.
chatSession_service_updateCustomData (update-custom-data.ts:59-80): add the salesforce_v2 arm using the same changed diff the HubSpot arm computes → inbox agent edits push (bare Priority or sf_case_Priority both resolve).

5D. Agent mapping, assignee sync, queue → team

Migrations

chatbot_users.salesforce_user_id text NULL + CREATE UNIQUE INDEX CONCURRENTLY … ON chatbot_users (chatbot_id, salesforce_user_id) WHERE salesforce_user_id IS NOT NULL (noTransaction = true) — the shape #2223 already wrote (20260815111500, 20260815111501); cherry-pick.
salesforce_escalation_teams.group_id uuid NULL REFERENCES groups(id) ON DELETE SET NULL + COMMENT ON COLUMN (“OpenCX team that owns Cases assigned to this Queue; NULL = escalation-only, no inbound routing”). Expose group_id in salesforce-escalation-team.dto.ts (satisfies binding keeps it honest) and pass through in create/update.

SalesforceAgentMappingService (new file salesforce-agent-mapping.service.ts, trimmed from #2223 — keep resolveOpenCxUserId(sfUser), resolveSalesforceUserId(openCxUserId); drop resolveIdentity/avatar):

SF User → member: stored salesforce_user_id, else case-insensitive email match on chatbot_users ⋈ users, persist NULL-only (WHERE salesforce_user_id IS NULL, tolerate 23505), never re-link a member already linked to a different SF id.
Member → SF User: stored, else SELECT Id,Name,Email FROM User WHERE IsActive=true AND Email='…' LIMIT 2 (SOQL value escaped via SalesforceCrmUtils.escapeSoqlValue), exactly one hit → persist.
Two SDK additions: getUserById, findActiveUsersByEmail.

SalesforceAssigneeSyncService (new file, Zendesk shape):

Gate: ticketing_system === salesforce_v2 + the flag for the direction.
Outbound syncAssigneeWithSalesforce({orgId, sessionId, openCxAssigneeId}) — called from a new case TicketingSystemEnum.SALESFORCE_V_2: in syncAssigneeToThirdParty (chat-integration.service.ts:217-232, lazy import like HubSpot’s). Requires linked case. Consume-once inbound-armed key salesforce_v2:case:assignee-sync:ignore:{caseId} → skip if present. Resolve target: AI_COPILOT_USER_ID → getCurrentUser().Id (the AI’s seat, same idea as HubSpot’s default_user_id); null → meta.salesforce_previous_owner_id if present else no-op (OwnerId is required in SF); user → mapped SF user, unmapped → skip with log. If target equals current owner → skip. Arm salesforce_v2:case:owner-echo:{caseId} = ownerId EX 15 then updateCaseOwner; on failure delete the key.
Inbound — inside handleOwnerChanged (salesforce-case.service.ts:2413-2479):
1. Read OwnerId. If owner-echo key equals it → DEL + return (our own write bouncing back).
2. Existing behaviour untouched when sync_assignee_from_3rd_party is off (early return on HANDED_OFF, handoff + “stepping back” comment on a non-integration owner, assignee_id = null).
3. When the flag is on: skip the HANDED_OFF early-return (an A→B reassignment must sync); on the first non-integration owner still do the handoff write + comment, but keep a human assignee_id when the new owner is a Queue (nullif(assignee_id, 555), from #2223); then syncAssigneeFromSalesforce: owner == integration user → assignSessionToAi (actor:{type:'integration'}); owner matches /^00G/ → SalesforceEscalationTeamsService.resolveGroupId(orgId, ownerId) (15/18-char tolerant, enabled, group_id IS NOT NULL, exactly one) → assignToTeam({shallowAssignment:true, actor:{type:'integration'}, trigger:'integration'}) if inbox_id differs; owner is a User → map → changeAssignee(actor:{type:'integration'}) if it differs; unmapped → leave as is. Before any changeAssignee/assignSessionToAi arm salesforce_v2:case:assignee-sync:ignore:{caseId} so the mirror-back is consumed and skipped (changeAssignee’s own assignee_id === agentId no-op guard is the primary safety, change-assignee.ts:44).
4. Existing syncSalesforceFieldsToCustomData call at the end stays.

No change to changeAssignee / assignSessionToAi signatures.

6. Echo / loop matrix

Scenario	Path	Terminates because
SF agent edits Priority	`case_updated` → refresh (diff: `sf_case_Priority`) → `ticket-updated`	Workflow that writes another SF field via `update-salesforce-case` re-syncs local first (`update-salesforce-case.action.ts:231-245`) → its echo has no diff
Workflow “Update Session Attributes” sets `sf_case_Priority`	merge (diff → `ticket-updated`) → reflect → `updateCase` → SF echo `case_updated` → refresh: no diff	Value already local
Inbox agent edits `Priority` (editable bag)	push → SF echo → refresh `custom_data.sf_case_Priority` (diff → ONE `ticket-updated`, legitimately: the Case changed) → stop	Second echo has no diff
OpenCX reassigns to human B	outbound arms `owner-echo=B_sf` → `updateCaseOwner` → `owner_changed` echo consumed → no handoff comment / no re-mirror	Consume-once key
SF agent reassigns Case to B	`owner_changed` → arm `assignee-sync:ignore` → `changeAssignee(B)` → mirror → outbound consumes → skip	Consume-once key + `changeAssignee` no-op guard
AI autofill writes fields	`updateCase` → echo → refresh: no diff (autofill already re-synced `salesforce-case-ai-fields.service.ts:541-554`)	—
A `ticket-updated` workflow writes the same value back	merge → `changedFields = []`	Diff is load-bearing (same contract as `contact-updated`)

7. Non-breaking / v1 safety checklist

New code lives in backend/src/salesforce-case-integration/**, the SALESFORCE_V_2 arm of syncAssigneeToThirdParty, and salesforce_v2-gated else if arms in the two custom-data write functions. V1 (salesforce) hits none of them: chat-integration.service.ts:219 keeps v1 in the no-op list; merge-custom-data.ts / update-custom-data.ts branch on 'salesforce_v2' only.
V1 webhook is a different controller (/backend/salesforce-case-management/webhook, salesforce-integration/salesforce.controller.ts:271-324) — the new case_updated type is invisible to it. MoneyGram’s caseId-only contract routes through handleCaseIdWebhook (salesforce-case.service.ts:356-367), untouched.
No change to SalesforceService.getConnection / token / verifyWebhookToken (salesforce-integration/salesforce.service.ts:915, 1344, 1361), to salesforce_integration_settings columns, to chat_sessions.salesforce_case_id or its unique index.
The shared append-note-to-ticket.ts:128-129 fall-through (v1 → V2 addCaseCommentWithEchoGuard) and resolve.service.ts:364-365 are not touched.
New behaviour is opt-in: case_updated requires the customer to add trigger 7; assignee sync requires the org flags (already false by default); queue routing requires group_id to be set; write-back only fires for keys that resolve to an updateable Case field on a salesforce_v2 org.
The only change to an existing path is stale sf_case_*/sf_contact_* keys now being cleared on refresh — a correctness fix, covered by tests.

8. Test plan (one scenario per file, local fake-Salesforce HTTP server + real Postgres/Redis, as in `salesforce-owner-and-assignee-stay-in-sync.spec.ts`; no mocks/spies)

backend/src/salesforce-case-integration/__tests__/

case-updated-webhook-refreshes-fields-and-fires-ticket-updated.spec.ts — ?type=case_updated → sf_case_* refreshed, salesforce_fields_updated row for whitelisted keys, ONE ticket-updated run with changedFields/previousValues.
case-updated-webhook-without-diff-fires-nothing.spec.ts — echo of an unchanged Case → no run, no chat_history row.
case-updated-clears-field-nulled-in-salesforce.spec.ts — key removed locally; changedFields includes it; whitelisted diff reports new: null.
case-updated-unknown-case-and-v1-org-are-ignored.spec.ts — no session / ticketing_system = salesforce → no SF read, no writes.
case-updated-concurrent-webhooks-serialize-per-case.spec.ts — two overlapping webhooks → newest snapshot wins.
custom-data-merge-pushes-sf-case-keys-to-case.spec.ts — merge action with sf_case_Priority → one PATCH with {Priority}; non-updateable / OwnerId / unknown keys skipped; v1 org → no PATCH.
editable-custom-data-edit-pushes-to-case.spec.ts — inbox edit Priority → PATCH; unchanged key → no PATCH.
owner-changed-assigns-mapped-teammate-when-sync-from-on.spec.ts — email auto-link persisted, changeAssignee with integration actor, no mirror-back PATCH.
owner-changed-integration-user-assigns-ai.spec.ts — owner back to integration user → assignee_id = 555, ai_closure_type cleared.
owner-changed-queue-owner-routes-to-mapped-team.spec.ts — 00G… with group_id → inbox_id set, human assignee preserved; unmapped/disabled/ambiguous → untouched.
owner-changed-legacy-behavior-when-sync-from-off.spec.ts — flag off → exactly today’s behaviour (handoff, null assignee, comment).
assignee-change-writes-case-owner-when-sync-to-on.spec.ts — human/AI/null cases; unmapped skipped; flag off → no PATCH.
assignee-echo-guard-suppresses-own-owner-write.spec.ts — outbound PATCH then owner_changed echo → no handoff, no comment.
agent-mapping-email-match-persists-and-isolates-orgs.spec.ts — NULL-only, cross-org isolation, 23505 tolerated.
escalation-teams-group-id-crud.spec.ts — DTO/CRUD round-trip, ON DELETE SET NULL.

backend/src/workflow/definitions/triggers/ticket-updated.trigger.spec.ts — payload shape, registry, changedFields/previousValues, no fire on empty diff (mirrors ticket-reopened.trigger.spec.ts). backend/src/chat-session/repo/merge-custom-data.spec.ts (new scenarios) — keysToClear removes keys; diff → fire; no-diff → no fire; reflect false → no push.

9. Delivery — one PR, four commits (each green on its own)

feat(workflows): add ticket-updated trigger, fired from session custom-data merges — trigger + enum + registry + keysToClear/diff/fire in merge-custom-data.ts + pnpm gensdk + tests.
feat(salesforce): refresh v2 Case fields on case_updated webhook — DTO/dispatch/handler/lock, stale-key clearing, diff of removed keys, docs (Apex method + trigger 7 + test class), tests.
feat(salesforce): push session attribute changes to the v2 Case — syncCustomDataToCase + the two reflect arms + tests.
feat(salesforce): sync Case owner with session assignee and map queues to teams — migrations + codegen, mapping + assignee-sync services, owner_changed changes, syncAssigneeToThirdParty arm, escalation-team group_id, docs section, tests.

Then: close #2229 and #2223 with a pointer to the new PR; open a separate PR for “For Each Matching Session” (already-decided semantics); #2227 stays independent. Estimated size ≈ 700–800 src lines + tests (vs 12k across the three open PRs).

10. Follow-ups (not in this PR)

Poll safety-net for orgs that cannot deploy Apex: SELECT … FROM Case WHERE SystemModstamp > :cursor over linked open sessions, mirroring salesforce-crm-poll-sync.worker.ts cadence/cursor idioms.
Manual agent-mapping endpoint + roster cache + dashboard picker (Zendesk PUT /agents/mapping shape); dashboard team picker for salesforce_escalation_teams.group_id.
Teammate identity/avatar on inbound SF comments/emails (the dropped half of #2223).
case_closed → run through the shared close path (fires ticket-resolved) + refresh fields.
Expose editable_custom_data in the ticket payload and fire ticket-updated on inbox edits.
Optional Apex Queueable retry wrapper for callouts, in the production checklist.

11. Decisions to confirm

Trigger name: ticket-updated (“Ticket Updated”) vs ticket-attributes-updated. Recommendation: ticket-updated, description makes the attribute scope explicit.
previousValues on the payload — keep (cheap, enables “from X to Y”) or drop for strict YAGNI. Recommendation: keep.
Queue → team storage: salesforce_escalation_teams.group_id (recommended, reuses the queue registry + CRUD) vs new groups.salesforce_queue_id.
case_updated refreshes Case + Contact + related objects (existing method, most current data) vs Case-only (#2229). Recommendation: reuse the existing method; add a caseOnly flag later only if API budget bites.

Overview

AI Chat Widget

AI X (Twitter) Support

AI WhatsApp Support

AI SMS Support

AI Phone Support

AI Email Support

AI Actions

Resources

2026 08 16 salesforce v2 two way sync design

Salesforce v2 — two-way Case sync, agent/queue mapping, `ticket-updated` trigger

1. Goal

2. Non-goals (explicitly deferred)

3. What exists on `main` (facts the design leans on)

4. Assessment of the open PRs

5. Design

5A. `ticket-updated` workflow trigger (generic, fired from the session custom-data seam)

5B. Inbound freshness — `type=case_updated` webhook

5C. Outbound write-back — attribute → Case field

5D. Agent mapping, assignee sync, queue → team

6. Echo / loop matrix

7. Non-breaking / v1 safety checklist

8. Test plan (one scenario per file, local fake-Salesforce HTTP server + real Postgres/Redis, as in `salesforce-owner-and-assignee-stay-in-sync.spec.ts`; no mocks/spies)

9. Delivery — one PR, four commits (each green on its own)

10. Follow-ups (not in this PR)

11. Decisions to confirm

​Salesforce v2 — two-way Case sync, agent/queue mapping, ticket-updated trigger

​1. Goal

​2. Non-goals (explicitly deferred)

​3. What exists on main (facts the design leans on)

​4. Assessment of the open PRs

​5. Design

​5A. ticket-updated workflow trigger (generic, fired from the session custom-data seam)

​5B. Inbound freshness — type=case_updated webhook

​5C. Outbound write-back — attribute → Case field

​5D. Agent mapping, assignee sync, queue → team

​6. Echo / loop matrix

​7. Non-breaking / v1 safety checklist

​8. Test plan (one scenario per file, local fake-Salesforce HTTP server + real Postgres/Redis, as in salesforce-owner-and-assignee-stay-in-sync.spec.ts; no mocks/spies)

​9. Delivery — one PR, four commits (each green on its own)

​10. Follow-ups (not in this PR)

​11. Decisions to confirm

Salesforce v2 — two-way Case sync, agent/queue mapping, `ticket-updated` trigger

1. Goal

2. Non-goals (explicitly deferred)

3. What exists on `main` (facts the design leans on)

4. Assessment of the open PRs

5. Design

5A. `ticket-updated` workflow trigger (generic, fired from the session custom-data seam)

5B. Inbound freshness — `type=case_updated` webhook

5C. Outbound write-back — attribute → Case field

5D. Agent mapping, assignee sync, queue → team

6. Echo / loop matrix

7. Non-breaking / v1 safety checklist

8. Test plan (one scenario per file, local fake-Salesforce HTTP server + real Postgres/Redis, as in `salesforce-owner-and-assignee-stay-in-sync.spec.ts`; no mocks/spies)

9. Delivery — one PR, four commits (each green on its own)

10. Follow-ups (not in this PR)

11. Decisions to confirm