Physician Portal & Mobile App Integration Specifications

Integration Summary

Note: HL7 v2.5.1 is not used directly by the Physician Portal; HL7 messages are handled by core HIS modules (e.g., LIS, RIS, CPOE) and exposed to the portal via internal APIs and FHIR. NABIDH/Malaffi considerations are still relevant for data provenance and consent.

INT-PHY-001: EHR & Patient Management

Business Context

What flows

• Inbound to Physician Portal
• Patient demographics, identifiers (MRN, Emirates ID), contact details
• Allergies, problem list, active diagnoses (ICD-10-AM), SNOMED CT terms
• Medication list (from PIS/CPOE), vital signs, recent results summary
• Clinical notes (H&P, progress, discharge summaries, consults)
• Care team assignments, encounters, locations
• Outbound from Physician Portal
• Mobile-entered clinical notes (progress notes, brief updates, consult notes)
• Updates to problems (e.g., mark as resolved), allergies (add/update)
• Note metadata (author, encounter, timestamps, source = physician_portal)

When

• Patient search / selection in portal or mobile app
• Patient chart opened or refreshed
• Note saved as draft or signed on mobile

Why

• Provide clinicians with up-to-date patient information while away from workstations.
• Allow mobile documentation to be part of the legal medical record in the core EHR.
• Support continuity of care and reduce reliance on phone calls and paper notes.

How often

• On-demand, near real-time REST calls per user interaction.
• Notes and updates posted immediately upon save/sign.

Error impact

• Inbound failure: Patient chart may show stale or incomplete data; clinician may need to fall back to workstation or call unit.
• Outbound failure: Mobile notes may remain local/queued; risk of documentation delay and medico-legal exposure if not recovered.
• Must comply with UAE PDPL for data minimisation and secure transmission.

FHIR R4 Technical Detail

The Physician Portal uses FHIR R4 to retrieve and update EHR data where exposed by the EHR & Patient Management module.

Resources

• Patient – demographics and identifiers
• AllergyIntolerance – allergies
• Condition – problems/diagnoses
• MedicationStatement / MedicationRequest – current meds
• Observation – vitals and key results
• Encounter – context
• Practitioner / CareTeam – providers
• DocumentReference or Composition / ClinicalImpression / Observation – for mobile notes (implementation choice)

Below is an example of a mobile-entered progress note represented as a FHIR Composition linked to the patient and encounter.

{
  "resourceType": "Composition",
  "id": "note-20260207-0001",
  "status": "final",
  "type": {
    "coding": [
      {
        "system": "http://snomed.info/sct",
        "code": "371530004",
        "display": "Progress note"
      }
    ],
    "text": "Progress Note"
  },
  "category": [
    {
      "coding": [
        {
          "system": "http://terminology.hl7.org/CodeSystem/document-classcodes",
          "code": "PN",
          "display": "Progress Note"
        }
      ]
    }
  ],
  "subject": {
    "reference": "Patient/2026009876",
    "display": "Fatima Al-Nahyan"
  },
  "encounter": {
    "reference": "Encounter/ENC2026020700456"
  },
  "date": "2026-02-07T10:45:00+04:00",
  "author": [
    {
      "reference": "Practitioner/PROV-10023",
      "display": "Dr. Ahmed Al-Maktoum"
    }
  ],
  "title": "Mobile Progress Note",
  "custodian": {
    "reference": "Organization/DUBAI-HOSPITAL",
    "display": "Dubai General Hospital"
  },
  "extension": [
    {
      "url": "http://gates-group.ae/fhir/StructureDefinition/source-system",
      "valueCode": "physician_portal"
    }
  ],
  "section": [
    {
      "title": "Subjective",
      "code": {
        "coding": [
          {
            "system": "http://loinc.org",
            "code": "29545-1",
            "display": "Subjective"
          }
        ]
      },
      "text": {
        "status": "generated",
        "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\">Patient reports improved shortness of breath overnight.</div>"
      }
    },
    {
      "title": "Objective",
      "code": {
        "coding": [
          {
            "system": "http://loinc.org",
            "code": "29546-9",
            "display": "Objective"
          }
        ]
      },
      "text": {
        "status": "generated",
        "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\">RR 18, SpO2 97% on room air, BP 120/75.</div>"
      }
    },
    {
      "title": "Assessment & Plan",
      "code": {
        "coding": [
          {
            "system": "http://loinc.org",
            "code": "51847-2",
            "display": "Assessment and plan note"
          }
        ]
      },
      "text": {
        "status": "generated",
        "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\">Stable. Continue current medications. Repeat chest X-ray tomorrow.</div>"
      }
    }
  ]
}

Key Element Mappings

For chart retrieval, the portal typically uses FHIR search bundles:

• GET /Patient?identifier=784-1985-1234567-1
• GET /Condition?patient=Patient/2026009876&clinical-status=active
• GET /AllergyIntolerance?patient=Patient/2026009876
• GET /Observation?patient=Patient/2026009876&category=vital-signs&_sort=-date&_count=20
• GET /Composition?patient=Patient/2026009876&type=http://snomed.info/sct|371530004&_sort=-date&_count=10

Search Parameters (examples)

Error Handling

• Network / API timeout
• Retry with exponential backoff: 5s, 15s, 30s, 60s (max 4 retries).
• If still failing, cache request in a secure local queue on device (for outbound notes) and mark chart as “offline data” for inbound.

• Display non-blocking banner to user: “Live EHR connection unavailable; showing last synced data.”

• 4xx from EHR FHIR API

• Parse OperationOutcome and log validation errors.
• For 401/403: trigger silent token refresh; if still unauthorized, force logout and re-authentication.

• For 409 (version conflict): re-fetch latest resource, prompt user to re-apply changes.

• 5xx from EHR FHIR API

• Treat as transient; retry with exponential backoff as above.

• If > 10 minutes continuous failure, raise alert to HIS operations team (email/SMS/on-call).

• Dead Letter Queue

• Any outbound note or update failing after max retries is stored in physician_portal_deadletter (internal) with payload, error, and provider.

• Portal Administrator dashboard shows items for manual re-submit or discard.

• Manual Recovery

• Admin can re-push failed notes to EHR after correcting mapping/config issues.
• If unrecoverable, export note as PDF and attach via EHR back-office tools, with audit trail.

Retry and Recovery

Retry Strategy:

Dead Letter Queue:

• Outbound notes/updates exhausting retries → physician_portal_deadletter table
• Admin dashboard for review, correction, and requeue
• Retention: 30 days active, then archive
• Alert: Portal Administrator notified on DLQ insertion

Idempotency:

• Deduplication key: [note_id]_[composition]_[signed_datetime]
• EHR checks for duplicate Composition.id before persisting
• Duplicate submissions return success without reprocessing

Reconciliation:

• Hourly check: portal-submitted notes vs EHR clinical_notes persistence confirmation
• Unmatched records flagged for Portal Administrator review
• Daily report: submission success rate, average latency, DLQ volume

INT-PHY-002: CPOE (Orders)

Business Context

What flows

• Outbound from Physician Portal
• Orders entered on mobile: medication, lab, imaging, nursing, consults, diets.
• Order metadata: priority, indication, comments, source = physician_portal.
• Inbound to Physician Portal
• Order status updates (e.g., pending, in_progress, completed, canceled).
• Unsigned order alerts (e.g., verbal orders requiring signature).

When

• Outbound: When physician signs an order in the mobile app.
• Inbound: When CPOE changes order status or flags unsigned orders.

Why

• Allow physicians to place and manage orders while mobile.
• Provide real-time visibility into order progress and pending actions.

How often

• Real-time, per order event.

Error impact

• Outbound failure: Order may not reach CPOE; risk of missed tests/medications.
• Inbound failure: Portal may show outdated order status; tasks may not be generated.

Technical Detail (Internal API)

This integration is internal (no HL7/FHIR directly from portal). CPOE handles HL7 to external systems.

Outbound Order Create (Portal → CPOE)

• POST /internal/cpoe/orders
• Payload (simplified):

{
  "source": "physician_portal",
  "patient_id": "2026009876",
  "encounter_id": "ENC2026020700456",
  "ordering_provider_id": "PROV-10023",
  "order_type": "LAB",
  "order_code": "718-7",
  "order_code_system": "LOINC",
  "order_display": "Hemoglobin [Mass/volume] in Blood",
  "priority": "ROUTINE",
  "indication_icd10am": "D64.9",
  "comments": "Check morning labs before ward round",
  "requested_datetime": "2026-02-07T10:50:00+04:00"
}

Inbound Order Status (CPOE → Portal)

• POST /internal/physician-portal/order-status
• Payload:

{
  "order_id": "ORD-20260207-00123",
  "patient_id": "2026009876",
  "status": "completed",
  "status_datetime": "2026-02-07T12:15:00+04:00",
  "source": "cpoe",
  "order_type": "LAB"
}

Portal maps these to:

• clinical_task_items (for unsigned orders, pending actions)
• physician_inbox_items (for certain status changes, e.g., canceled by lab)

Error Handling

• Outbound order create failure
• Retry with exponential backoff: 2s, 10s, 30s, 60s (max 4).
• If still failing, mark order as “Not sent to CPOE” in UI and create a high-priority task for the provider.

• Log to integration monitoring with patient, provider, and order details.

• Inbound status failure

• If portal endpoint unavailable, CPOE retries with backoff.
• After max retries, CPOE flags the order as “portal notification failed”; no clinical impact on actual order execution, but portal may show stale status.

• Nightly reconciliation job compares CPOE orders with portal tasks and corrects discrepancies.

• Dead Letter

• Failed inbound messages stored in physician_portal_inbound_deadletter with raw payload for replay.

• Manual Recovery

• Admin can trigger reconciliation for a specific encounter or provider.
• For critical orders (e.g., STAT), on-call IT notified if portal not receiving updates.

Retry and Recovery

Retry Strategy:

Dead Letter Queue:

• Failed outbound orders → physician_portal_deadletter with full order payload
• Failed inbound status messages → physician_portal_inbound_deadletter with raw payload
• Admin dashboard for replay and correction
• Retention: 30 days active, then archive
• STAT order failures trigger immediate IT on-call notification

Idempotency:

• Outbound deduplication key: [order_id]_[patient_id]_[submission_datetime]
• CPOE checks for duplicate order submissions before processing
• Inbound status deduplication: [order_id]_[status]_[status_datetime] — duplicate updates ignored

Reconciliation:

• Nightly reconciliation: compare CPOE orders with portal task and inbox items
• Discrepancies auto-corrected where possible (e.g., missing status updates applied)
• Monthly trend: portal order submission success rate, average round-trip latency

INT-PHY-003: LIS (Lab Results & Critical Values)

Business Context

What flows

• Inbound only to Physician Portal:
• Lab results (final and amended) with values, units, reference ranges, abnormal flags.
• Critical value notifications with priority and required acknowledgment.

When

• When LIS finalizes a result or flags a critical value.
• LIS typically sends HL7 ORU^R01 to core HIS; HIS exposes results to portal via FHIR and internal notifications.

Why

• Enable timely review of lab results on mobile.
• Support DOH/DHA expectations for critical result acknowledgment tracking.
• Improve patient safety by reducing delays.

How often

• Real-time push from HIS to portal as events occur.

Error impact

• Failure delays visibility of new/critical results in portal.
• Core HIS still holds results; clinicians can access via workstation, but mobile alerts may be missed.

FHIR R4 Technical Detail

Resources

• DiagnosticReport – lab report
• Observation – individual test results
• Task or internal event – for critical acknowledgment

Sample DiagnosticReport + Observation

{
  "resourceType": "Bundle",
  "type": "collection",
  "entry": [
    {
      "fullUrl": "DiagnosticReport/lab-DR-20260207-001",
      "resource": {
        "resourceType": "DiagnosticReport",
        "id": "lab-DR-20260207-001",
        "status": "final",
        "category": [
          {
            "coding": [
              {
                "system": "http://terminology.hl7.org/CodeSystem/v2-0074",
                "code": "LAB",
                "display": "Laboratory"
              }
            ]
          }
        ],
        "code": {
          "coding": [
            {
              "system": "http://loinc.org",
              "code": "58410-2",
              "display": "Complete blood count (hemogram) panel - Blood"
            }
          ],
          "text": "CBC"
        },
        "subject": {
          "reference": "Patient/2026009876",
          "display": "Fatima Al-Nahyan"
        },
        "encounter": {
          "reference": "Encounter/ENC2026020700456"
        },
        "effectiveDateTime": "2026-02-07T11:30:00+04:00",
        "issued": "2026-02-07T11:45:00+04:00",
        "performer": [
          {
            "reference": "Organization/DUBAI-LAB",
            "display": "Dubai General Hospital Laboratory"
          }
        ],
        "result": [
          {
            "reference": "Observation/lab-Hb-20260207-001"
          }
        ]
      }
    },
    {
      "fullUrl": "Observation/lab-Hb-20260207-001",
      "resource": {
        "resourceType": "Observation",
        "id": "lab-Hb-20260207-001",
        "status": "final",
        "category": [
          {
            "coding": [
              {
                "system": "http://terminology.hl7.org/CodeSystem/observation-category",
                "code": "laboratory",
                "display": "Laboratory"
              }
            ]
          }
        ],
        "code": {
          "coding": [
            {
              "system": "http://loinc.org",
              "code": "718-7",
              "display": "Hemoglobin [Mass/volume] in Blood"
            }
          ],
          "text": "Hemoglobin"
        },
        "subject": {
          "reference": "Patient/2026009876"
        },
        "encounter": {
          "reference": "Encounter/ENC2026020700456"
        },
        "effectiveDateTime": "2026-02-07T11:30:00+04:00",
        "issued": "2026-02-07T11:45:00+04:00",
        "performer": [
          {
            "reference": "Organization/DUBAI-LAB"
          }
        ],
        "valueQuantity": {
          "value": 6.5,
          "unit": "g/dL",
          "system": "http://unitsofmeasure.org",
          "code": "g/dL"
        },
        "interpretation": [
          {
            "coding": [
              {
                "system": "http://terminology.hl7.org/CodeSystem/v3-ObservationInterpretation",
                "code": "CL",
                "display": "Critically low"
              }
            ]
          }
        ],
        "referenceRange": [
          {
            "low": {
              "value": 12.0,
              "unit": "g/dL",
              "system": "http://unitsofmeasure.org",
              "code": "g/dL"
            },
            "high": {
              "value": 16.0,
              "unit": "g/dL",
              "system": "http://unitsofmeasure.org",
              "code": "g/dL"
            }
          }
        ]
      }
    }
  ]
}

Key Mappings

Search Parameters

Portal typically queries HIS FHIR API:

• GET /DiagnosticReport?patient=Patient/2026009876&category=LAB&_sort=-issued&_count=20
• GET /Observation?patient=Patient/2026009876&code=718-7&_sort=-date&_count=10

Error Handling

• Inbound push failure (HIS → Portal)
• HIS retries with exponential backoff: 10s, 30s, 60s, 120s (configurable).

• If portal endpoint unavailable > 15 minutes, HIS logs and raises integration alert; results remain accessible via EHR.

• Portal processing error

• If payload invalid for portal, store raw bundle in physician_portal_inbound_deadletter with error.

• Attempt schema migration if minor version mismatch; otherwise require manual fix.

• Critical result acknowledgment

• If portal cannot create acknowledgment task, HIS must still enforce acknowledgment via workstation.
• Reconciliation job compares LIS critical results with portal acknowledgments to ensure completeness.

Retry and Recovery

Retry Strategy:

Dead Letter Queue:

• Failed inbound result notifications → physician_portal_inbound_deadletter with full FHIR bundle
• Admin dashboard for review, schema correction, and replay
• Retention: 30 days active, then archive
• Critical result delivery failures trigger immediate alert to IT and Patient Safety

Idempotency:

• Deduplication key: [diagnostic_report_id]_[status]_[issued_datetime]
• Portal checks for existing physician_inbox_items before creating duplicate result notifications
• Duplicate pushes acknowledged without reprocessing

Reconciliation:

• Hourly: compare LIS critical results with portal acknowledgement records
• Unacknowledged critical results after 30 minutes escalated regardless of portal delivery status
• Daily: overall result delivery success rate and latency report
• Monthly: critical result acknowledgement compliance rate per DOH/DHA requirements

INT-PHY-004: RIS (Radiology Reports & Critical Findings)

Business Context

What flows

• Inbound radiology reports and critical finding alerts for display in portal and mobile app.

When

• When radiologist signs a report or flags a critical finding.

Why

• Provide timely access to imaging results and critical findings for on-call physicians.
• Support DOH/DHA expectations for timely communication of critical imaging findings.

How often

• Real-time per report.

Error impact

• Portal may not show latest imaging reports; clinicians may rely on workstation/PACS.

FHIR R4 Technical Detail

Resource

• DiagnosticReport (imaging category)
• Optional ImagingStudy (for linking to PACS viewer via DICOM)

Sample DiagnosticReport

{
  "resourceType": "DiagnosticReport",
  "id": "rad-DR-20260207-010",
  "status": "final",
  "category": [
    {
      "coding": [
        {
          "system": "http://terminology.hl7.org/CodeSystem/v2-0074",
          "code": "RAD",
          "display": "Radiology"
        }
      ]
    }
  ],
  "code": {
    "coding": [
      {
        "system": "http://loinc.org",
        "code": "36626-4",
        "display": "CT Chest"
      }
    ],
    "text": "CT Chest"
  },
  "subject": {
    "reference": "Patient/2026009876",
    "display": "Fatima Al-Nahyan"
  },
  "encounter": {
    "reference": "Encounter/ENC2026020700456"
  },
  "effectiveDateTime": "2026-02-07T09:30:00+04:00",
  "issued": "2026-02-07T10:00:00+04:00",
  "performer": [
    {
      "reference": "Organization/ABUDHABI-RAD",
      "display": "Abu Dhabi Imaging Center"
    }
  ],
  "resultsInterpreter": [
    {
      "reference": "Practitioner/PROV-20011",
      "display": "Dr. Layla Hassan (Radiologist)"
    }
  ],
  "conclusion": "No evidence of pulmonary embolism. Mild bilateral basal atelectasis.",
  "conclusionCode": [
    {
      "coding": [
        {
          "system": "http://snomed.info/sct",
          "code": "373572006",
          "display": "No abnormality detected"
        }
      ]
    }
  ]
}

Key Mappings

Error Handling

• Inbound push failure (HIS → Portal)
• HIS retries with exponential backoff: 10s, 30s, 60s, 120s (configurable).

• If portal endpoint unavailable > 15 minutes, HIS logs and raises integration alert; reports remain accessible via EHR/PACS.

• Portal processing error

• If payload invalid, store raw bundle in physician_portal_inbound_deadletter with error.

• Attempt schema migration if minor version mismatch; otherwise require manual fix.

• Critical finding acknowledgment

• If portal cannot create acknowledgment task, HIS must still enforce acknowledgment via workstation.
• Reconciliation job compares RIS critical findings with portal acknowledgments.

Retry and Recovery

Retry Strategy:

Dead Letter Queue:

• Failed inbound report notifications → physician_portal_inbound_deadletter with full FHIR DiagnosticReport
• Admin dashboard for review, correction, and replay
• Retention: 30 days active, then archive
• Critical finding delivery failures trigger immediate alert to IT and Radiology

Idempotency:

• Deduplication key: [diagnostic_report_id]_[status]_[issued_datetime]
• Portal checks for existing physician_inbox_items before creating duplicate report notifications
• Duplicate pushes acknowledged without reprocessing

Reconciliation:

• Hourly: compare RIS critical findings with portal acknowledgement records
• Unacknowledged critical findings after 30 minutes escalated regardless of portal delivery status
• Daily: overall report delivery success rate and latency
• Monthly: critical finding acknowledgement compliance rate per DOH/DHA requirements

INT-PHY-005: PIS (Medication Data)

Business Context

What flows

• Inbound to Physician Portal:
• Current medication list, dispensing status, pharmacist interventions.

When

• When medication is dispensed or pharmacist creates an intervention.

Why

• Provide real-time medication visibility on mobile.

How often

• Real-time per event.

Error impact

• Portal may show stale medication list; clinicians can access via workstation.

Error Handling

• Same pattern as INT-PHY-003 (HIS-initiated push to portal).
• If portal unavailable, PIS events queued in HIS and delivered when portal recovers.

Retry and Recovery

Retry Strategy:

Dead Letter Queue:

• Failed medication update notifications → physician_portal_inbound_deadletter
• Admin dashboard for review and replay
• Retention: 30 days active, then archive

Idempotency:

• Deduplication key: [medication_order_id]_[event_type]_[event_datetime]
• Duplicate pushes acknowledged without reprocessing

Reconciliation:

• Nightly: compare PIS active medication list vs portal cached medication data
• Discrepancies auto-corrected on next portal medication list refresh

INT-PHY-006: Scheduling

Business Context

What flows

• Bidirectional:
• Inbound: Provider schedule, patient lists, census, on-call rosters.
• Outbound: Schedule adjustments, availability status, swap requests.

When

• On-demand when physician views schedule; when swap requests are created/resolved.

Why

• Enable mobile schedule management and on-call coordination.

How often

• On-demand.

Error impact

• If unavailable, portal shows cached schedule with stale-data warning; swap requests disabled.

Error Handling

• API timeout: show cached schedule with banner; retry in background.
• Swap request failure: queue locally; notify physician of pending submission.

Retry and Recovery

Retry Strategy:

Dead Letter Queue:

• Failed swap requests → physician_portal_deadletter with full request payload
• Admin dashboard for review and resubmission
• Retention: 30 days active, then archive

Idempotency:

• Swap request deduplication key: [requester_id]_[target_provider_id]_[slot_datetime]
• Scheduling module rejects duplicate swap requests

Reconciliation:

• Hourly: compare portal-cached schedule vs Scheduling module current state
• Auto-refresh portal cache on discrepancy detection
• Daily: swap request completion rate and average resolution time

INT-PHY-007: Patient Portal (Messaging)

Business Context

What flows

• Bidirectional:
• Inbound: Patient messages with attachments and read status.
• Outbound: Physician replies, clinical advice entries.

When

• When patient sends message or physician replies.

Why

• Enable secure patient-provider communication via mobile.

How often

• Real-time per message event.

Error impact

• If delivery fails, message queued; patient may not receive timely reply.

Error Handling

• Delivery failure to Patient Portal: retry with backoff; if persistent, flag in sender's inbox.
• Inbound message processing failure: store in DLQ; create system alert.

Retry and Recovery

Retry Strategy:

Dead Letter Queue:

• Failed outbound messages → physician_portal_deadletter
• Failed inbound messages → physician_portal_inbound_deadletter
• Admin dashboard for review and replay
• Retention: 30 days active, then archive

Idempotency:

• Deduplication key: [message_id]_[sender_id]_[sent_datetime]
• Patient Portal rejects duplicate message deliveries

Reconciliation:

• Hourly: compare portal outbound message log vs Patient Portal delivery confirmations
• Undelivered messages after 1 hour flagged for IT review
• Daily: message delivery success rate and average latency

INT-PHY-008: Push Notification Service (APNS/FCM)

Business Context

What flows

• Outbound only:
• Push notification payloads for critical alerts, new results, messages, schedule changes.
• Deep-link metadata for direct navigation to relevant screen.

When

• On notifiable events as configured in Notification Rules and physician_preferences.

Why

• Ensure timely awareness of critical events when physician is not actively in the app.

How often

• Real-time per event.

Error impact

• Missed push notifications; physician relies on in-app inbox when app is next opened.

Error Handling

• APNS/FCM delivery failure: logged; inbox item still created as fallback.
• Invalid device token: mark token as invalid in physician_portal_accounts; do not retry.
• Rate limiting by APNS/FCM: queue and throttle per platform limits.

Retry and Recovery

Retry Strategy:

Dead Letter Queue:

• Push notifications are fire-and-forget with inbox fallback; no DLQ required
• Failed deliveries logged in push_notification_log for analytics
• Invalid tokens trigger device re-registration flow on next app open

Idempotency:

• Deduplication key: [event_type]_[entity_id]_[event_datetime]
• Prevent duplicate push for same event within 60-second window

Reconciliation:

• Daily: push delivery success rate by platform (iOS vs Android)
• Weekly: invalid token cleanup and re-registration rate
• Monthly: notification engagement metrics (tap-through rate)