Case-System Sync Failure Triage Playbook

A reviewed intake was approved, but its contact, matter, or generated documents never showed up in the case-management system, or the record still shows a failed or stuck sync. This playbook takes on-call from that symptom to a confirmed root cause with read-only diagnostics first, then a least-to-most-invasive fix menu. Work top to bottom. Do not re-push or recreate anything until you have read the evidence, because a blind retry against a legal record can duplicate a matter.

Use this playbook when a reviewed intake's data or documents did not appear in the case-management system (PracticePanther), or a record shows a failed or stuck sync status in the admin view.

Common triggers:

• An approved intake shows a failed or stuck sync status per record [1366].
• A contact or matter is missing from the case system after review [2425].
• Generated documents synced late or not at all while contact data landed [1371].
• Every connected account starts failing token exchange at once [1098].

If the record was never approved in review, this is not a sync failure. See Decision points.

Classify by blast radius first, then by legal-work visibility.

Impact is legal work, not just a red status. A missing matter or an unattached document means a firm cannot act on a real client record, so weigh blast radius against the sensitivity of the records held.

Assign these before touching anything. Keep names generic and fill from rotation.

• Sync/on-call owner: runs the triage tree, decides mitigations, owns the timeline.
• Reviewer/data steward: confirms the record passed review and validates recovered data against the source scan.
• Integration/API escalation: subject expert for the case-management API, OAuth, and the transport-level fallback.
• Comms lead: posts status, fields firm-facing questions, shields the owner.

For a single stuck record the owner may hold every role. For an all-accounts auth outage, split comms and pull in integration escalation immediately.

Run diagnostics in this order. Everything here is read-only. Do not retry, requeue, or recreate anything until the decision tree points you there.

1. Read the per-record SYNC STATUS in the admin view to see where the record stalled [1366].
2. Read the audit log for the failed write. Every sync is captured, so the failed step is traceable end-to-end [2425].
3. Check the retry queue and per-attempt tracking for stuck jobs, including per-attempt scan tracking [2425][1108].
4. Confirm OAuth token refresh is healthy and not WAF-blocked. Check whether token and refresh complete across accounts [1098][2425].
5. Determine whether the create failed on a 409 duplicate conflict or a genuine validation error [1069].
6. Check the Drive-bridge upload and replace queue for documents that never attached to the matter [1371].
7. Confirm the record actually passed human review before it was ever eligible to sync [2424][1268].

Read-only diagnostic checklist:

[ ] Per-record sync status read in the admin view
[ ] Audit-log entry located for the failed write
[ ] Retry queue / per-attempt tracking checked for stuck jobs
[ ] OAuth token + refresh healthy across accounts (not WAF-blocked)
[ ] Create failure classified: 409 duplicate vs genuine validation error
[ ] Drive-bridge upload/replace queue checked for unattached documents
[ ] Record confirmed approved in human review (not still held/soft-locked)

Branch on what the read-only pass showed.

• If ALL accounts fail token exchange, it is a WAF or transport block on OAuth, not a per-record fault [1098].
• If a single write failed and is retryable, it belongs in the retry queue [2425][1108].
• If create returns 409, it is the duplicate/minimal-update path, not an error. Duplicate matching supports phone last-8 matching [1069].
• If contact data synced but documents did not, the fault is in the Drive-bridge upload queue [1371].
• If the record never left review, it was not approved and should not have synced at all [2424].

Reserve the Error path for genuine validation failures only. A 409 conflict is expected duplicate behavior, not a validation error [1069].

Apply the least invasive fix that resolves the confirmed root cause. Move up the list only when the cheaper fix does not fit the evidence.

1. Re-drive the record from its visible sync status in the admin view [1366].
2. Let the retry queue re-attempt the failed write, or manually requeue the stuck job [2425][1108].
3. Route a 409 create to the minimal-update fallback: apply the minimal update and write the matched CRM record ID back [1069].
4. Re-push documents through the Drive bridge so generated files write to the linked Google Drive folder and attach to the matter, using the queue's replace behavior [1371].
5. Reshape the OAuth request at the transport layer to clear the WAF block when the managed HTTP client is silently blocked [1098].

The transport-level fallback is the most invasive fix because it affects the auth path for every account. Do not reach for it on a single stuck record.

Escalate the moment a cheaper fix does not fit the evidence.

• Escalate to the case-management API vendor and the WAF owner when token exchange fails across all accounts and a transport reshape does not clear it [1098].
• Escalate to integration/API escalation when the Drive-bridge queue stays stalled after a re-push [1371].
• Pull in the reviewer/data steward before any recreate, to confirm the record and its data against the source scan [2424].

Verify against the case system, not just the sync status.

1. Confirm the contact and matter now exist in the case-management system, with custom fields populated [2425].
2. Confirm the generated document is attached to the matter from the linked Drive folder [1371].
3. Confirm the audit log holds a clean entry for the completed write and the record shows a green sync status [1366][2425].
4. For a 409 recovery, confirm the matched CRM record ID was written back and no duplicate matter was created [1069].

Capture evidence while it is fresh, before retries overwrite it.

• The record ID and its per-record sync status [1366].
• The audit-log entry for the failed write [2425].
• The retry-attempt count from per-attempt tracking [1108].
• The OAuth response, including any WAF block signature on the token exchange [1098].

Firm-facing status template:

[SEV-x] Intake sync — <UPDATE>
Impact: <record(s) affected; contact/matter/document missing>
Root cause: <confirmed/suspected — WAF auth, retry-queue, 409 duplicate, Drive-bridge, not-approved>
Action: <read-only diagnostics done / mitigation applied; auto-sync paused if recreating>
Next update: <time>

Book a short retro and turn the root cause into a preventative action.

• Keep per-record sync status visible so a black-box integration stays monitorable and re-drivable [1366].
• Keep the retry queue and audit log in place so every failed write is recoverable and every sync is traceable end-to-end [2425][1108].
• Keep the duplicate path explicit: handle 409 conflicts with a minimal update and write the matched record ID back, instead of treating them as errors [1069].
• Keep the transport-level fallback ready for when a managed HTTP client is silently WAF-blocked on OAuth [1098].
• Keep the review gate before sync: only generate and sync downstream documents after a reviewer approves the scanned intake against the editable form [2424][1268].
• Decouple slow work from the request path with background processing and automatic retry, so transient failures recover without a human re-submitting the packet [1110].