Skip to content

Write-Back Design (MTG-076)

Status: Draft scaffold — decisions pending. This document captures the open questions and decision log for the Jarvis → Oscar billing module write-back path. It blocks MTG-074 (converter implementation) and MTG-075 (timeline scoping).

Problem Statement

Per NPD-213, Jarvis generates OHIP billing code recommendations from an encounter note, the provider reviews them, and the accepted codes land in Oscar's billing module as real billing_on_cheader1 + billing_on_item rows. The round-trip between Jarvis and Oscar needs a FHIR-level contract covering:

  • HTTP semantics (verb, idempotency)
  • Invoice.status lifecycle and transitions
  • Provider-review intermediate state
  • Mapping accepted codes back to Oscar columns
  • Error / rejection handling
  • Payment-model detection at write time

Decisions Required

1. HTTP verb and endpoint

  • Options:
  • POST /api/fhir/r4/Invoice — Jarvis creates a new Invoice; server assigns Oscar's billing_on_cheader1.id.
  • PUT /api/fhir/r4/Invoice/{id} — client-supplied id; Oscar must reconcile.
  • Custom operation $create-from-encounter — higher-level, carries encounter reference + dx context.
  • Leaning: POST. Matches existing SMART-on-FHIR R4 server conventions at /api/fhir/r4/**.
  • Open: idempotency key header (If-None-Exist or custom X-Jarvis-Recommendation-Id).

2. Invoice.status lifecycle

FHIR Invoice.status required binding: draft | issued | balanced | cancelled | entered-in-error.

  • Option A: Jarvis POSTs draft → provider reviews → PATCH to issued. Two round-trips per bill.
  • Option B: Jarvis holds the recommendation client-side; provider accepts; Jarvis POSTs issued directly. One round-trip but no server-side audit trail of the draft.
  • Option C: Jarvis POSTs draft but the status transition to issued is implicit on provider-accept via a custom operation ($accept-recommendation).

Leaning: Option A. Maps cleanly to existing FHIR state-machine patterns and gives Oscar a server-side audit of recommendations-generated-but-not-accepted.

Implication for Oscar: billing_on_cheader1.status has no draft equivalent in its 10-code enum; may need a new code or a dedicated jarvis_draft flag column (decision for Oscar team).

3. Idempotency on re-submit

Scenario: network hiccup; Jarvis retries the POST for the same provider-accepted recommendation.

  • Options:
  • Server-side dedup on (patient, encounter, recommendation-uuid) tuple
  • If-None-Exist header search on a Jarvis-generated business identifier
  • Let Oscar dedup post-facto via existing billing_on_cheader1.header_id uniqueness

Leaning: If-None-Exist with a Jarvis recommendation UUID on Invoice.identifier. Standard FHIR idempotency pattern.

4. Provider-review intermediate state

  • Does the draft → issued transition happen via Jarvis client (provider clicks Accept in Nexus), via a Nexus-side PATCH, or via a custom Oscar action?
  • What's the UI for "batch end-of-day review" (NPD-213 acceptance criteria)?
  • Decision needed with: Shawn / Diana (Nexus UX).

5. Rejected-claim / remittance handling (Phase 1 scope decision)

Escalation open with Muhammad (2026-04-21):

  • NPD-213 acceptance: "Rejected claims include the rejection reason and suggested correction"
  • MTG-071 v2.4 + this IG scopes Oscar raDetail (remittance advice) to Phase 2
  • If Phase 1 needs the rejection loop: MTG-074 must add ClaimResponse profile + converter, Jarvis must poll or subscribe, and the state machine above gains cancelled + rejection-reason extensions. Timeline risk for 2026-06-24.
  • If deferred to Phase 2: Phase 1 writes land as issued and Jarvis considers them "done." Rejections surface via out-of-band Oscar UI.

6. Payment-model detection at write time

Source signals (per MTG-071 v2.4):

  • provider.onMohLastRosterReportDate populated → capitation model (FHO/FHN)
  • demographic_ext row with key ENROLLMENT_PROVIDER pointing at the provider → patient is rostered
  • Historical billing_on_cheader1.status = 'H' count per provider → shadow-bill behavior
  • Not in Oscar: explicit FHO vs FHN vs FHG distinction (payer-side designation)

Leaning: ProviderBillingModelService helper queries the signals above and returns an enum (FHO_FHN | FHG | FFS | UNKNOWN). Jarvis calls this before writing to decide whether the generated codes should be status='H' (shadow) or status='O' (FFS). FHO+ (launching April 2026) may need a config override.

7. Reverse-mapping requirements for InvoiceConverter.toOscarObject

See fhir-to-oscar.yaml + the "Write-back implementation checklist" in fhir-to-oscar.md. Key items MTG-074 must handle:

  • oscarBillingStatus extension takes precedence over FHIR Invoice.status when both are set
  • Invoice.status = 'draft' → new Oscar column or flag (see §2)
  • Parse lineItem.priceComponent.amount.value back to Oscar's String fee field
  • Parse lineItem.priceComponent.factor back to Oscar's String ser_num
  • Reverse-map $ICD9CM URI → literal "icd9" on dx Coding.system
  • Handle idempotency via If-None-Exist lookup on Jarvis recommendation UUID

Out of Scope (Phase 1)

  • Multi-province support (AB AHCIP, BC MSP, SK MSB, MB Health)
  • Juno (non-Oscar) EMR source
  • Pre-service eligibility check (CoverageEligibilityRequest)
  • Patient-facing ExplanationOfBenefit view
  • Payer-submission FHIR Claim (Oscar submits via H-file, not FHIR)

Checklist — Required Decisions Before MTG-074 Starts

  • [ ] HTTP verb (POST vs PUT vs custom operation)
  • [ ] Invoice.status lifecycle (Option A vs B vs C)
  • [ ] Idempotency key strategy
  • [ ] Provider-review UX + transition trigger (Shawn/Diana)
  • [ ] Phase 1 rejected-claim scope (Muhammad escalation)
  • [ ] Payment-model detection helper scope (Oscar-side helper vs Jarvis-side)
  • [ ] Oscar-side column/flag additions (draft state, Jarvis recommendation UUID)
  • Upstream: NPD-213 Jarvis Billing Recommendation with OSCAR context
  • Mapping (reverse): FHIR to Oscar — governs the write path
  • Mapping (forward): Oscar to FHIR — governs the read path
  • Blocks: MTG-074 (converter implementation), MTG-075 (timeline scoping)