Skip to content

Write-Back Design

Status: Provisional — the decisions on this page are open. It records the options under consideration for the Jarvis → Oscar billing write-back path and what would settle each of them. The converter work depends on these being settled first.

Problem Statement

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 is the UI for "batch end-of-day review"?
  • Decision needed with: the IG owners and Nexus UX.

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

Not settled:

  • Requirement: "Rejected claims include the rejection reason and suggested correction"
  • The source-table analysis and this IG scope Oscar raDetail (remittance advice) to Phase 2
  • If Phase 1 needs the rejection loop: the converter work must add a ClaimResponse profile + converter, Jarvis must poll or subscribe, and the state machine above gains cancelled + rejection-reason extensions.
  • 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 the source-table analysis):

  • 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 the converter 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 Converter Work 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 (IG owners + Nexus UX)
  • [ ] Phase 1 rejected-claim scope
  • [ ] Payment-model detection helper scope (Oscar-side helper vs Jarvis-side)
  • [ ] Oscar-side column/flag additions (draft state, Jarvis recommendation UUID)
  • Upstream: Jarvis billing recommendations with Oscar context
  • Mapping (reverse): FHIR to Oscar — governs the write path
  • Mapping (forward): Oscar to FHIR — governs the read path
  • Blocks: the converter implementation and its timeline scoping