d_s_bisht/devsofttech_hms_ci4
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
9d568463f1
devsofttech_hms_ci4/ABDM_UNIFIED_CONSULT_BUNDLE_SESSION.md

7.3 KiB
Raw Blame History

Session Handover: Unified OPD Consultation Bundle & Single Care Context Integration

Date: October 6, 2026
Status: ✅ Complete, Deployed & Verified on Live Environment
Target Repository: HMS_CI4_OLD (origin/main) & HMS-ABDM-Gateway (origin/AG_version)
Live Server: hms-live (root@hms-live)

1. Problem Statement & User Requests

  1. Default OTP Customization:
    • The user requested updating the default sandbox OTP for ABDM care context linking to 654321 while preserving backward compatibility.
  2. Duplicate Records in PHR App (Image 5):
    • Previously, a single OPD consultation visit generated 3 distinct records/care contexts:
      • OPD-15353-S33727-20261006
      • PRESC-15353-S33727-20261006
      • WELLNESS-33727-20261006
    • In the PHR application (e.g. ABHA App), this caused duplicate entries where OPConsultation and WellnessRecord appeared separately for the exact same visit.
  3. Mislabeled Invoice Records (Images 2 & 3):
    • Older records for OPD invoices showed both Prescription and Invoice because historical rows had hi_type = 'OPConsultRecord' or lacked strict HI-type separation.
  4. Unified NRCES Bundle:
    • The user requested consolidating into a single unified bundle & care context for the OPD visit.
    • The care context display must dynamically reflect the clinical contents: OPD Consult, Wellness, Prescription, HealthDocument (including vitals, prescribed medicines, and scanned/uploaded files).
  5. Auto-Generate / Update on Print:
    • Automatically compile or update the FHIR record whenever the consultation form is saved or printed in HMS.

2. Technical Implementation Details

A. NRCES FHIR R4 Specification Conformance

  • Profile: https://nrces.in/ndhm/fhir/r4/StructureDefinition/OPConsultRecord
  • Following the ABDM standard, an OPConsultRecord Document Bundle natively contains all clinical sections:
    1. Chief Complaints: Condition / complaint entries.
    2. Physical Examination / Vitals: Observation resources for Blood Pressure, Pulse, Temperature, \text{SpO}_2, Weight, and Height.
    3. Problems & Diagnoses: Condition resources with SNOMED CT and ICD-10 codings.
    4. Medications / Prescriptions: MedicationRequest resources with dose, frequency, and instructions.
    5. Investigation Advice: ServiceRequest for recommended tests/imaging.
    6. Follow-Up Appointment: Appointment resource for next visit date.
    7. Document References: Binary / DocumentReference for uploaded scans and generated prescription PDFs.
  • Bundle Meta Hardening:
    • Added required 'versionId' => '1' and 'lastUpdated' => $issuedAt across all builder methods in app/Libraries/FhirR4Builder.php.
    • Validated using NRCES FHIR validator (validate_fhir tool): 0 structural errors.

B. Single Care Context & Cleanup of Redundant Records

  • File: app/Controllers/Opd_prescription.php
    • In storePrescriptionFhirBundle(), unified generation to compile only the single OPConsultRecord.
    • Removed generation of separate PRESC-... and WELLNESS-... records.
    • Automatically cleans up redundant standalone entries (PRESC-..., WELLNESS-..., and old alias patterns) from health_records and opd_fhir_documents.
    • In resolveRecentFhirPushStatus(), relaxed session reference search to '-S' . $sessionId . '-'.

C. Clinical Component Labeling & Alias Deduplication

  • File: app/Controllers/AbdmGateway.php
    • In findCareContextsForPatient():
      • Automatically builds dynamic component labels: OPD Consult, Wellness, Prescription - Dr. Name - Date (dynamically appends , HealthDocument if external reports or scans exist).
      • Length guarded to 85 characters to ensure clean display across all PHR apps.
      • Registers all aliases in $seenRefs (OPD-{patientId}-S{sessionId}-{cleanDate}, OPD-{opdId}-S{sessionId}-{visitDate}, etc.).
      • Tracks $seenOpdSessions: step 6c fallback suppresses any orphaned or legacy alias references matching an already processed OPD session.

D. ABDM Bridge Gateway HI-Type Resolution Fix

  • File: /var/www/html/abdm-bridge-gateway/app/Controllers/AbdmGateway.php on hms-live
    • Modified resolveAbdmHiTypeFromContext() to apply strict prefix checking (INVOICE- \rightarrow Invoice, OPD- \rightarrow OPConsultation, WELLNESS- \rightarrow WellnessRecord, etc.) before loose keyword searching on the display string.
    • This prevents composite titles like "OPD Consult, Wellness" from being misclassified into WellnessRecord.

E. Task Board Synchronization Hardening

  • File: app/Libraries/Abdm/Sync/AbdmTaskBoardSyncService.php
    • In queryEligibleOpdVisits(): sorted opd_fhir_documents to prioritize OPConsultRecord over legacy PrescriptionRecord.
    • Standardized care context reference derivation to canonical OPD-{patientId}-S{sessionId}-{cleanDate}.
    • In linkAndPushOpdRecord(): checks existing record by care_context_reference before inserting to prevent duplicate queued rows.
    • In syncSingleWorkTask(): applies canonical OPD reference format and OPConsultRecord prioritization.

F. Auto-Generation on Consultation Print & PDF

  • File: app/Controllers/Opd.php
    • Added auto-generation / updating hook inside opd_lettre_print() and opd_lettre_pdf().
    • When the consultation letter is printed or downloaded, storePrescriptionFhirBundle() is invoked in the background, updating opd_fhir_documents and health_records.

3. Live Verification & Database Status

Target Test Patient:

  • Patient ID: 15353 (P26081015353)
  • ABHA Address: 91310013085603@sbx
  • OPD ID: 33793
  • Session ID: 33727

Care Context Output:

V3 Care Contexts Count: 2
  [0] ref=OPD-15353-S33727-20261006
      display=OPD Consult, Wellness, Prescription - Dr. Jayashri Joshi - 06 Oct 2026
      hiType=OPConsultation
  [1] ref=INVOICE-OPD-33793-2026-10-06
      display=Invoice D26100033793 (OPD - Rs 1,000.00)
      hiType=Invoice

Database health_records State on hms-live:

id patient_id hi_type care_context_reference push_status
243 15353 InvoiceRecord INVOICE-OPD-33793-2026-10-06 linked
244 15353 OPConsultRecord OPD-15353-S33727-20261006 local_discovery_ready

(Legacy duplicate queued rows 247, 248, 249 and stale PrescriptionRecord document 123 were deleted).

Print Hook Verification:

  • Executing opd_lettre_print(33727) completes cleanly and updates health_records row 244 with latest timestamp.

4. Git Commits & Push Summary

HMS_CI4_OLD (main branch):

  • 04eff5e: Standardize OPD care context formatting and prevent duplicate session aliases
  • b0a0811: fix(fhir): add versionId and lastUpdated to DocumentBundle meta for full NRCES conformance
  • e2bb0b1: fix(abdm): enrich OPD and INVOICE care contexts with clinical components and bill summary
  • f367603: fix(abdm): unify consult visit into single OPConsultRecord bundle and auto-sync on print
  • d46f222: fix(abdm): set default sandbox linking OTP to 654321 and accept both 654321 and 123456

abdm-bridge-gateway (AG_version branch on hms-live):

  • eff0fe6: fix(abdm): strict prefix precedence for hiType resolution to prevent multi-component display hijacking
  • Pushed to https://github.com/infodevsofttech-admin/HMS-ABDM-Gateway.git