Scheduling & Bed/OR Management Integration Specifications

Integration Summary

INT-SCH-001: EHR & Patient Management

Business Context

What flows

• Inbound from EHR/Patient Mgmt:
• Patient demographics and identifiers (MRN, Emirates ID, mobile, address).
• Outbound from Scheduling:
• Encounter creation and updates (encounter class/type/status, admission/discharge times).
• Appointment details (date/time, provider, department, status).

When

• Appointment booked/updated/cancelled.
• Inpatient admission, transfer, discharge.
• Demographic updates impacting scheduled encounters.

Why

• Maintain a single source of truth for patient and encounter records.
• Ensure all clinical modules reference the canonical encounter owned by Scheduling.
• Keep EHR timelines and problem lists aligned with encounter lifecycle.

How often

• Real-time, per event.

Error impact

• Failed inbound demographics: appointment booking may be blocked or use stale data.
• Failed outbound encounter/ADT: downstream modules (clinical, billing) may not see the encounter; risk of documentation and charging gaps.

HL7 v2.5.1 Technical Detail (Internal ADT)

Used when the EHR/Patient Management component consumes ADT-style events from Scheduling.

Message Types

• ADT^A04 – Outpatient registration (appointment-based encounter shell).
• ADT^A01 – Inpatient admission.
• ADT^A02 – Transfer.
• ADT^A03 – Discharge.
• ADT^A08 – Update patient/visit information.

Sample: Outpatient Registration ADT^A04

MSH|^~\&|HIS_SCHED|DUBAIHOSP|HIS_EHR|DUBAIHOSP|20260207101530||ADT^A04^ADT_A01|SCH20260207101530001|P|2.5.1|||AL|NE||UTF-8
EVN|A04|20260207101525|||USR1001^ALI^FATIMA^^^MS
PID|1||MRN100234^^^DUBAIHOSP^MR~784-1990-1234567-3^^^UAE^EID||AL-MAKTOUM^AHMED^HASSAN||19900315|M|||PO BOX 12345^^DUBAI^^00000^AE||+971501234567|||M||||||||||AE
PV1|1|O|OPD^CLINIC1^ROOM05^DUBAIHOSP^^^^CLINIC|R|||PROV2001^KHAN^SARA^AHMED^^DR|||MED|||||||ENC20260207100001^^^DUBAIHOSP^VN||||||||||||||||||||20260207103000
PV2|||^^^DUBAIHOSP^^^^^ROUTINE OUTPATIENT||||||||||||||||||||||||||||||||||||||||||20260207103000
ZAP|1|APT20260207100055|CONSULT_NEW|20260207103000|30|SCHEDULED

Key Segment Notes

• PID-3: MRN and Emirates ID (UAE PDPL: both treated as identifiers requiring protection).
• PV1-2: O for outpatient, I for inpatient.
• PV1-19: Visit/encounter number (encounters.encounter_id).
• PV1-3: Mapped from appointments.department_id, locations.location_id, facilities.facility_id.
• ZAP (custom segment):
• ZAP-2: appointments.appointment_id
• ZAP-3: appointment_types.type_id
• ZAP-4: appointments.appointment_datetime
• ZAP-5: appointments.duration_minutes
• ZAP-6: appointments.status

Field Mapping to Scheduling Tables

FHIR R4 Technical Detail (Internal API)

Internal EHR components may use FHIR for encounter and appointment access.

Resources

• Encounter – canonical encounter.
• Appointment – outpatient bookings.

Sample Encounter (Outpatient)

{
  "resourceType": "Encounter",
  "id": "ENC20260207100001",
  "status": "arrived",
  "class": {
    "system": "http://terminology.hl7.org/CodeSystem/v3-ActCode",
    "code": "AMB",
    "display": "ambulatory"
  },
  "type": [
    {
      "coding": [
        {
          "system": "http://terminology.hl7.org/CodeSystem/v2-0004",
          "code": "O",
          "display": "Outpatient"
        }
      ],
      "text": "New consultation"
    }
  ],
  "subject": {
    "reference": "Patient/MRN100234",
    "display": "Ahmed Al-Maktoum"
  },
  "participant": [
    {
      "individual": {
        "reference": "Practitioner/PROV2001",
        "display": "Dr. Sara Ahmed Khan"
      }
    }
  ],
  "period": {
    "start": "2026-02-07T10:30:00+04:00"
  },
  "serviceProvider": {
    "reference": "Organization/DUBAIHOSP",
    "display": "Dubai General Hospital"
  },
  "appointment": [
    {
      "reference": "Appointment/APT20260207100055"
    }
  ]
}

Key Element Mappings

Search Parameters

• GET /Encounter?patient={patient-id}
• GET /Encounter?date=ge2026-02-01&date=le2026-02-29
• GET /Appointment?patient={patient-id}&status=booked
• GET /Appointment?practitioner={provider-id}&date=2026-02-07

Error Handling

Manual recovery:

• Admin UI to re-publish ADT/FHIR events for a given encounter or appointment.
• Reconciliation report comparing EHR encounters vs scheduling encounters daily.

Retry and Recovery

Retry Strategy

• Trigger: Internal API network error or HL7 ACK timeout.
• Non-retryable: HL7 AE/AR or FHIR 4xx validation errors — route to DLQ for data correction.

Circuit Breaker (for REST API calls)

Dead Letter Queue

• Storage: integration_message_log entries with status IN ('failed', 'rejected') and endpoint = 'EHR_PATIENT_MGMT'.
• Visibility: Admin UI with filter by endpoint, status, and age.
• Retention: 30 days.
• Resolution workflow: Support team reviews DLQ entry → corrects data (identifiers, codes) → triggers re-publish via admin UI → status updated.
• Alerting: Dashboard alert if DLQ depth > 5 or any entry aged > 12 hours.

Idempotency

• Deduplication key: encounter_id + appointment_id for encounter/appointment events.
• EHR-side: Treats encounter_id and appointment_id as natural keys; duplicate events perform upsert.
• HL7: MSH-10 (Message Control ID) used for deduplication on receiver side.

Reconciliation

• Frequency: Daily at 02:00.
• Process: Compare encounters and appointments tables between Scheduling and EHR for the past 24 hours. Flag discrepancies (missing encounters, status mismatches) for manual review.
• Report: Reconciliation discrepancies on admin dashboard and in daily integration health report.

INT-SCH-002: CPOE

Business Context

What flows

• Inbound:
• Admission, transfer, discharge, and OR booking orders from CPOE.
• Outbound:
• Encounter context (encounter_id, class, location).
• OR schedule and case details for display in CPOE.

When

• Physician signs admission/discharge/transfer order.
• Physician submits procedure/OR booking request.
• Scheduling confirms OR slot or updates bed/encounter status.

Why

• Ensure orders are actionable: admissions create real bed assignments; procedures get OR time.
• Provide clinicians with real-time view of bed and OR availability.

How often

• Real-time per order.

Error impact

• Failed inbound: admission orders may not result in actual bed assignment; OR requests may be lost.
• Failed outbound: CPOE may show outdated encounter status or OR schedule, affecting clinical decisions.

(Internal REST only; no HL7/FHIR externally required here.)

Technical Detail (Internal REST)

Key Endpoints (illustrative)

• POST /scheduling/admissions – from CPOE when admission order signed.
• POST /scheduling/discharges – discharge order signed.
• POST /scheduling/or-requests – OR booking request.
• GET /scheduling/or-schedule?date=...&room=... – CPOE queries OR schedule.
• GET /scheduling/encounters/{encounter_id} – encounter context.

Payloads use internal JSON DTOs aligned with encounters, beds, or_cases, or_schedules.

Error Handling

• Retries from CPOE client with exponential backoff (5s, 15s, 30s).
• If admission request fails after retries:
• CPOE flags order as “Pending bed assignment – system error”.
• Bed Management Coordinator notified via dashboard.
• OR booking failures:
• CPOE displays conflict reason (rule violation, no room).
• No auto-retry; user must adjust request.

Dead-letter:

• All failed requests logged with payload and error in integration_message_log for manual replay.

Retry and Recovery

Timeout and Circuit Breaker (synchronous internal integration)

• Admission/discharge order failures: After retries exhausted, CPOE flags order and Bed Management Coordinator is notified via dashboard. Manual bed assignment via Scheduling UI serves as fallback.
• OR booking failures: No automatic retry; CPOE displays conflict reason to user. User must adjust request parameters (room, time, team) and resubmit.

Dead Letter Queue

• Storage: integration_message_log entries with status = 'failed' and endpoint = 'CPOE'.
• Visibility: Admin UI for manual replay of failed requests.
• Retention: 14 days.
• Resolution workflow: Support team reviews payload and error → corrects or replays via admin UI.
• Alerting: Alert Bed Management Coordinator for failed admission orders; alert OR Scheduler for failed OR requests.

Idempotency

• Deduplication key: order_id from CPOE order.
• Scheduling-side: Admission and OR booking endpoints check for existing active request with same order_id; duplicates return existing resource rather than creating new.

Reconciliation

• Frequency: Twice daily (08:00 and 20:00).
• Process: Compare CPOE admission/discharge orders with Scheduling encounter statuses. Flag orders without corresponding encounter updates (or vice versa) for manual review.
• Report: Discrepancies on Bed Management dashboard and OR Scheduler dashboard.

INT-SCH-003: Billing & Claims

Business Context

What flows

• Outbound from Scheduling:
• Encounter creation/closure.
• Admission/discharge dates and times.
• Bed assignment history and bed type (for bed charges).
• OR case details (duration, room, procedure code) for OR charges.

When

• Encounter created/updated/closed.
• Bed assigned/released.
• OR case completed.

Why

• Drive accurate room-and-board and OR utilization billing.
• Provide LOS and discharge disposition for DRG grouping and UAE payer rules (e.g., Daman, THIQA).

How often

• Real-time.

Error impact

• Missing ADT/encounter events → unbilled stays or incorrect LOS.
• Missing bed/OR data → revenue leakage.

HL7 v2.5.1 Technical Detail (ADT to Billing)

Billing may consume ADT messages similar to EHR, with additional financial fields.

Message Types

• ADT^A01 – Admission.
• ADT^A02 – Transfer (ward/bed changes).
• ADT^A03 – Discharge.
• ADT^A08 – Update (e.g., payer change).

Sample: Inpatient Admission ADT^A01

MSH|^~\&|HIS_SCHED|ABUDHABIHOSP|BILLING|ABUDHABIHOSP|20260207112000||ADT^A01^ADT_A01|SCH20260207112000001|P|2.5.1|||AL|NE||UTF-8
EVN|A01|20260207111950|||USR2001^OMAR^LAILA^^^MS
PID|1||MRN200567^^^ABUDHABIHOSP^MR~784-1982-7654321-8^^^UAE^EID||AL-NAHYAN^FATIMA^MOHAMMED||19820520|F|||PO BOX 54321^^ABU DHABI^^00000^AE||+971502223344|||M||||||||||AE
PV1|1|I|4A^401^02^ABUDHABIHOSP^^^^WARD4A|R|||PROV3001^HASSAN^ALI^^^DR|||MED|||||||ENC20260207110001^^^ABUDHABIHOSP^VN||||||||||||||||||||20260207111500
PV2||||||||||||||||||||||||||||||||||||||||||20260210120000
IN1|1|DAMAN|PLN-DMN-GOLD|Daman Insurance PJSC|PO BOX 128888^^ABU DHABI^^00000^AE|+97126000000|||||784-1982-7654321-8^^^UAE^EID|AL-NAHYAN^FATIMA^MOHAMMED|19820520|F|||||||||||||||||||||||||||||||
DG1|1||I10^Essential (primary) hypertension^ICD-10-AM||20260207111500||A
ZBE|1|BED3004|4A^401^02^ABUDHABIHOSP|20260207111500||

Key Segment Notes

• IN1: Payer and plan (Daman, THIQA, Oman Insurance).
• PV2-9/10: Expected discharge date/time (used for LOS planning).
• DG1: Admission diagnosis (ICD-10-AM).
• ZBE (custom bed segment):
• ZBE-2: beds.bed_id
• ZBE-4: bed_assignments.assigned_datetime
• ZBE-5: bed_assignments.released_datetime (if known).

Field Mapping

FHIR R4 Technical Detail (Optional)

If Billing uses FHIR, Encounter and EpisodeOfCare can be exposed similarly to INT-SCH-001. No additional FHIR-specific structures are required beyond that.

Error Handling

• HL7 transmission failure:
• Retry 30s, 2m, 5m; after 3 failures, mark encounter as “billing_sync_pending”.
• HL7 AE/AR:
• No auto-retry; billing team notified; correction and manual resend.
• Data consistency:
• Daily reconciliation of LOS and bed days between Scheduling and Billing.

Retry and Recovery

Retry Strategy

• Trigger: HL7 transport failure or REST API 5xx error.
• Non-retryable: HL7 AE/AR or REST 4xx — route to DLQ for correction by billing team.

Circuit Breaker (for REST API calls)

Dead Letter Queue

• Storage: integration_message_log entries with status IN ('failed', 'rejected') and endpoint = 'BILLING'.
• Visibility: Integration Exceptions dashboard with RCM-specific filter.
• Retention: 60 days (billing audit requirements).
• Resolution workflow: RCM/IT reviews → corrects data (payer codes, encounter details) → triggers manual resend → billing processes corrected payload.
• Alerting: Email + dashboard alert to RCM if any encounter marked billing_sync_pending for > 4 hours.

Idempotency

• Deduplication key: encounter_id + ADT event type (A01/A02/A03/A08).
• Billing-side: Uses encounter_id as natural key; duplicate ADT events for the same event type perform upsert. Bed assignment changes (A02) are additive and timestamped.

Reconciliation

• Frequency: Daily at 01:00.
• Process: Compare LOS (admission_datetime to discharge_datetime) and bed assignment history between Scheduling and Billing for all encounters discharged in the past 24 hours. Flag discrepancies (missing bed days, incorrect LOS, unmatched OR charges).
• Report: Reconciliation results on RCM dashboard and in daily billing operations report.
• KPI: Billing sync success rate target >= 99.9%.

INT-SCH-004: Cleaning Management

Business Context

What flows

• Outbound events when a bed becomes vacant:
• Bed identifier, ward, previous patient encounter, discharge/transfer time.
• Cleaning priority (routine, terminal, isolation).

When

• Patient discharged (A03) or transferred out of a bed (A02) and bed released.

Why

• Automate cleaning task creation to reduce bed turnaround time and support Bed Board accuracy.

How often

• Real-time per bed release.

Error impact

• Missed events → bed not cleaned promptly → reduced capacity and infection control risk.

Technical Detail (Event / REST)

Event Payload Example

{
  "eventType": "BED_VACATED",
  "eventId": "EVT-20260207-00045",
  "timestamp": "2026-02-07T13:05:00+04:00",
  "bed": {
    "bedId": "BED3004",
    "facilityId": "ABUDHABIHOSP",
    "departmentId": "WARD4A",
    "locationId": "4A-401-02"
  },
  "encounterId": "ENC20260207110001",
  "vacatedReason": "DISCHARGE",
  "priority": "ROUTINE",
  "isIsolation": true
}

Cleaning system either subscribes to an event bus topic (e.g., bed.vacated) or exposes POST /cleaning/tasks for direct calls.

Error Handling

• Event bus delivery guarantees (at-least-once).
• Cleaning system must treat eventId as idempotent.
• If REST call fails:
• Retry 1m, 5m, 15m; after that, flag bed as “Cleaning task not created” on Bed Board and alert housekeeping supervisor.

Retry and Recovery

Retry Strategy

• Trigger: REST call failure or event delivery failure.
• Non-retryable: Cleaning system returns 4xx (e.g., invalid bed ID) — flag for master data correction.

Dead Letter Queue

• Storage: integration_message_log entries with status = 'failed' and endpoint = 'CLEANING'.
• Visibility: Bed Board shows “Cleaning task not created” badge on affected beds; Integration Exceptions dashboard.
• Retention: 14 days.
• Resolution workflow: Housekeeping Supervisor or IT reviews → corrects bed master data if needed → triggers manual task creation via Cleaning module UI or admin resend.
• Alerting: Immediate alert to Housekeeping Supervisor for any failed cleaning notification (infection control implications).

Idempotency

• Deduplication key: eventId (e.g., EVT-20260207-00045).
• Cleaning-side: Must treat eventId as idempotent key; duplicate events do not create duplicate cleaning tasks.
• Event bus: At-least-once delivery guarantee; Cleaning system designed to handle duplicates safely.

Reconciliation

• Frequency: Every 4 hours.
• Process: Compare beds with cleaning_status = pending in Scheduling against active cleaning tasks in Cleaning module. Beds with pending status but no corresponding cleaning task are flagged and a new task is auto-created.
• Report: Discrepancies on Bed Board and in Housekeeping Supervisor's shift report.
• KPI: Bed turnaround time target (discharge to clean-ready) monitored via this integration.

INT-SCH-005: Nutrition Management

Business Context

What flows

• Outbound ADT-like notifications:
• Admission, transfer, discharge.
• Ward/bed, encounter id.
• Basic diet flags (e.g., NPO, diabetic diet) if available from CPOE or EHR.

When

• ADT A01/A02/A03 events.

Why

• Maintain accurate dietary census and tray routing.

How often

• Real-time.

Error impact

• Incorrect meal delivery or missed meals; operational inefficiency.

HL7 v2.5.1 Technical Detail

Nutrition may consume a simplified ADT feed.

Sample: Transfer ADT^A02

MSH|^~\&|HIS_SCHED|DUBAIHOSP|NUTRITION|DUBAIHOSP|20260207123000||ADT^A02^ADT_A02|SCH20260207123000001|P|2.5.1|||AL|NE||UTF-8
EVN|A02|20260207122945|||USR3002^SALEH^HIND
PID|1||MRN100234^^^DUBAIHOSP^MR~784-1990-1234567-3^^^UAE^EID||AL-MAKTOUM^AHMED^HASSAN||19900315|M
PV1|1|I|4B^412^01^DUBAIHOSP^^^^WARD4B|R|||PROV2001^KHAN^SARA^AHMED^^DR|||MED|||||||ENC20260207100001^^^DUBAIHOSP^VN||||||||||||||||||||20260207120000
PV2||||||||||||||||||||||||||||||||||||||||||20260210120000
ZDT|1|DIABETIC|REGULAR|NPO_AFTER_MIDNIGHT

ZDT (custom diet segment) can be populated from CPOE or EHR if available; otherwise omitted.

Field Mapping

Error Handling

• Same retry/alert pattern as INT-SCH-004.
• Nutrition system should fall back to manual census if feed unavailable (operational policy).

Retry and Recovery

Retry Strategy

• Trigger: HL7 transport failure or REST API error.
• Non-retryable: HL7 AE/AR — flag for data correction (e.g., invalid ward/bed code).

Dead Letter Queue

• Storage: integration_message_log entries with status = 'failed' and endpoint = 'NUTRITION'.
• Visibility: Integration Exceptions dashboard; Nutrition module shows "Census may be incomplete" banner if recent failures detected.
• Retention: 14 days.
• Resolution workflow: Nutrition Supervisor or IT reviews → corrects data → triggers manual resend. In parallel, Nutrition team can manually update census from Bed Board data.
• Alerting: Alert Nutrition Supervisor for any failed ADT notification near meal service times (06:00, 11:00, 17:00 local).

Idempotency

• Deduplication key: MSH-10 (HL7 Message Control ID) or encounter_id + event type (REST).
• Nutrition-side: Uses encounter_id + ward/bed as key for census entries; duplicate messages update existing records.

Reconciliation

• Frequency: Three times daily (before each meal service: 05:30, 10:30, 16:30).
• Process: Compare Scheduling's active inpatient census (encounters with encounter_status = admitted, current bed assignments) against Nutrition's dietary census. Add missing patients to census; remove discharged patients not yet reflected.
• Report: Census discrepancy report to Nutrition Supervisor before each meal service.
• Fallback: If ADT feed is completely unavailable, Nutrition falls back to manual census from Bed Board (operational policy).

INT-SCH-006: Patient Portal

Business Context

What flows

• Outbound to Portal:
• Available slots (Slot), provider schedules (Schedule), booked appointments (Appointment), encounter references.
• Inbound from Portal:
• Appointment booking requests, cancellations, rescheduling.

When

• Patient searches for appointments, books or cancels.
• Scheduling changes provider availability or appointment status.

Why

• Enable self-service booking and reduce call center load.
• Improve patient experience and transparency.

How often

• On-demand via REST.

Error impact

• Failed booking: patient may think appointment is booked when it is not (must avoid).
• Stale availability: double-booking risk (must use transactional checks).

FHIR R4 Technical Detail

Resources

• Slot – atomic availability.
• Schedule – provider/session availability.
• Appointment – booking.
• Encounter – reference only (read-only).

Sample Slot

{
  "resourceType": "Slot",
  "id": "SLOT-20260207-DRSARA-1030",
  "status": "free",
  "schedule": {
    "reference": "Schedule/SCHED-DRSARA-CLINIC1"
  },
  "start": "2026-02-07T10:30:00+04:00",
  "end": "2026-02-07T11:00:00+04:00",
  "serviceType": [
    {
      "coding": [
        {
          "system": "http://example.ae/codes/appointment-type",
          "code": "CONSULT_NEW",
          "display": "New Consultation"
        }
      ]
    }
  ],
  "comment": "Dubai General Hospital - Internal Medicine Clinic 1"
}

Sample Appointment (Booked via Portal)

{
  "resourceType": "Appointment",
  "id": "APT20260207100055",
  "status": "booked",
  "serviceCategory": [
    {
      "coding": [
        {
          "system": "http://terminology.hl7.org/CodeSystem/service-category",
          "code": "GP",
          "display": "General Practice"
        }
      ]
    }
  ],
  "serviceType": [
    {
      "coding": [
        {
          "system": "http://example.ae/codes/appointment-type",
          "code": "CONSULT_NEW",
          "display": "New Consultation"
        }
      ]
    }
  ],
  "specialty": [
    {
      "coding": [
        {
          "system": "http://snomed.info/sct",
          "code": "394802001",
          "display": "General medical practice"
        }
      ]
    }
  ],
  "start": "2026-02-07T10:30:00+04:00",
  "end": "2026-02-07T11:00:00+04:00",
  "created": "2026-02-05T09:15:00+04:00",
  "participant": [
    {
      "actor": {
        "reference": "Patient/MRN100234",
        "display": "Ahmed Al-Maktoum"
      },
      "status": "accepted"
    },
    {
      "actor": {
        "reference": "Practitioner/PROV2001",
        "display": "Dr. Sara Ahmed Khan"
      },
      "status": "accepted"
    }
  ],
  "slot": [
    {
      "reference": "Slot/SLOT-20260207-DRSARA-1030"
    }
  ],
  "comment": "Booked via patient portal (Arabic interface)."
}

Key Element Mappings

Search Parameters

• GET /Slot?schedule=Schedule/SCHED-DRSARA-CLINIC1&start=ge2026-02-07T00:00:00+04:00&status=free
• GET /Appointment?patient=Patient/MRN100234&date=ge2026-02-01
• GET /Appointment?practitioner=Practitioner/PROV2001&status=booked

Booking Flow

1. Portal calls GET /Slot to show free slots.
2. Patient selects slot and submits POST /Appointment with slot reference.
3. Scheduling service: - Validates patient identity (via portal token). - Checks slot still free and scheduling rules. - Creates appointments row and updates appointment_slots.current_bookings. - Returns created Appointment with 201 Created.
4. On success, encounter shell is created internally (not exposed directly to portal).

Error Handling

• Concurrency:
• If slot already taken, return 409 Conflict with FHIR OperationOutcome explaining “Slot no longer available”.
• Validation errors:
• Return 400 Bad Request with OperationOutcome.
• Portal network errors:
• Portal should not assume booking success without HTTP 201; show clear message and allow retry.
• Retry:
• For 5xx errors, portal may retry once; further retries risk double-booking and should be avoided.

Retry and Recovery

Timeout and Circuit Breaker (synchronous FHIR API)

• Read failures (GET): Portal may display cached slot data with "Availability may not be current" notice. Cache TTL: 2 minutes for slot data.
• Write failures (POST/PUT): Portal must not assume booking was created. Clear error message: "Your booking could not be confirmed. Please try again or contact us."
• Concurrency (409 Conflict): Portal displays "This slot is no longer available" and refreshes available slots.

Dead Letter Queue

• Not applicable for portal reads (stateless queries).
• For portal-initiated bookings that fail: portal stores failed request in local pending state and offers "Retry" button. No server-side DLQ for portal write failures.

Idempotency

• Booking deduplication: Portal generates a client-side requestId (UUID) sent as a header. Scheduling server checks for duplicate requestId before creating appointment; returns existing appointment if duplicate detected.
• Slot locking: When patient selects a slot, portal acquires a soft lock (2-minute TTL) via PATCH /Slot/{id} with status = busy-tentative. If booking is not confirmed within 2 minutes, lock expires and slot becomes free again.

Reconciliation

• Frequency: Hourly.
• Process: Compare portal's local appointment cache against Scheduling's canonical appointments table. Stale or missing bookings are refreshed. Appointments cancelled in Scheduling but still showing as active in portal cache are corrected.
• Report: Portal admin dashboard shows sync status and any pending discrepancies.

INT-SCH-007: NABIDH (Dubai HIE)

Business Context

What flows

• Outbound ADT messages for Dubai-licensed facilities:
• Admissions, transfers, discharges, outpatient registrations, demographic updates.

When

• Any ADT event for encounters at Dubai facilities.

Why

• Comply with DHA/NABIDH requirements for real-time encounter sharing.
• Enable cross-facility care coordination in Dubai.

How often

• Real-time per event.

Error impact

• Non-compliance with DHA requirements.
• Incomplete patient history in NABIDH for Dubai residents.

NABIDH HL7 v2.5.1 Profile

NABIDH uses constrained ADT profiles (based on v2.5.1) with:

• Mandatory Emirates ID in PID-3 or PID-18.
• Facility identifiers aligned with DHA registry.
• Use of ADT^A01/A02/A03/A04/A08.

Sample: Admission ADT^A01 to NABIDH

MSH|^~\&|HIS_SCHED|DUBAIHOSP|NABIDH|DHA|20260207114530||ADT^A01^ADT_A01|NAB20260207114530001|P|2.5.1|||AL|NE||UTF-8
EVN|A01|20260207114500|||USR1001^ALI^FATIMA^^^MS
PID|1||MRN100234^^^DUBAIHOSP^MR~784-1990-1234567-3^^^AE^EID||AL-MAKTOUM^AHMED^HASSAN||19900315|M|||PO BOX 12345^^DUBAI^^00000^AE||+971501234567|||M||||||||||AE
PV1|1|I|4B^412^01^DUBAIHOSP^^^^WARD4B|R|||PROV2001^KHAN^SARA^AHMED^^DR|||MED|||||||ENC20260207110001^^^DUBAIHOSP^VN||||||||||||||||||||20260207114000
PV2||||||||||||||||||||||||||||||||||||||||||20260210120000
DG1|1||I10^Essential (primary) hypertension^ICD-10-AM||20260207114000||A
ZID|1|784-1990-1234567-3|EID

NABIDH-Specific Requirements

• PID-3 must include Emirates ID with correct assigning authority (AE^EID).
• MSH-3/4 and MSH-5/6 must use DHA-registered application/facility codes.
• EVN-2 event timestamp is mandatory.
• PV1-44 admit datetime and PV1-45 discharge datetime must be populated where applicable.

Acknowledgement Handling

• NABIDH returns ACK messages with:
• MSA-1 = AA (accept), AE (error), or AR (reject).
• Scheduling integration engine:
• Stores outbound message and ACK in integration_message_log.
• Retries on transport failure; does not auto-resend on AE/AR (requires correction).

Error Handling

• Transport failure (MLLP/TLS):
• Retry 1m, 5m, 15m; after 3 failures, mark messages as “pending NABIDH” and alert integration team.
• AE/AR:
• Log full message and error; provide reconciliation UI to fix identifiers/codes and resend.
• Compliance:
• Daily report of NABIDH submission rate (KPI: ≥ 99.5%).

Retry and Recovery

Retry Strategy

• Trigger: MLLP/TLS transport failure or no ACK within 30 seconds.
• Non-retryable: ACK with AE or AR — route to DLQ for manual correction of identifiers, codes, or configuration.

Dead Letter Queue

• Storage: integration_message_log rows with status IN ('failed', 'rejected') and endpoint = 'NABIDH'.
• Visibility: Integration Exceptions dashboard filtered by NABIDH endpoint.
• Retention: 90 days (regulatory compliance).
• Resolution workflow: Integration Admin reviews → corrects identifiers/codes (e.g., invalid Emirates ID format, unregistered facility code) → triggers resend via reconciliation UI → system updates status.
• Alerting: Email + dashboard alert if DLQ depth > 10 messages or any message aged > 24 hours.

Idempotency

• Deduplication key: MSH-10 (Message Control ID).
• NABIDH-side: Expected to deduplicate by MSH-10; safe to resend.
• HIS-side: On ACK receipt, match MSA-2 to integration_message_log.message_control_id.

Reconciliation

• Frequency: Daily at 03:00.
• Process: Compare ADT events generated by Scheduling for Dubai facilities (facilities.emirate = 'Dubai') in the past 24 hours against integration_message_log entries with endpoint = 'NABIDH' and status = 'acked'. Events without successful transmission are flagged for re-send.
• Report: NABIDH submission rate report (target >= 99.5%) on Integration dashboard and in daily operations report to HIM Supervisor.
• KPI: NABIDH ADT Submission Rate tracked continuously.

INT-SCH-008: Malaffi (Abu Dhabi HIE)

Business Context

What flows

• Outbound ADT messages for Abu Dhabi-licensed facilities:
• Admissions, transfers, discharges, outpatient registrations, updates.

When

• Any ADT event for encounters at Abu Dhabi facilities.

Why

• Comply with DOH/Malaffi requirements and ADHICS guidelines.
• Support longitudinal patient record across Abu Dhabi providers.

How often

• Real-time.

Error impact

• Non-compliance with DOH.
• Missing encounter data in Malaffi.

Malaffi HL7 v2.5.1 Profile

Similar to NABIDH but with DOH-specific facility codes and potentially different required fields.

Sample: Discharge ADT^A03 to Malaffi

MSH|^~\&|HIS_SCHED|ABUDHABIHOSP|MALAFI|DOH|20260207160000||ADT^A03^ADT_A03|MAL20260207160000001|P|2.5.1|||AL|NE||UTF-8
EVN|A03|20260207155930|||USR2001^OMAR^LAILA^^^MS
PID|1||MRN200567^^^ABUDHABIHOSP^MR~784-1982-7654321-8^^^AE^EID||AL-NAHYAN^FATIMA^MOHAMMED||19820520|F|||PO BOX 54321^^ABU DHABI^^00000^AE||+971502223344|||M||||||||||AE
PV1|1|I|4A^401^02^ABUDHABIHOSP^^^^WARD4A|R|||PROV3001^HASSAN^ALI^^^DR|||MED|||||||ENC20260207110001^^^ABUDHABIHOSP^VN||||||||||||||||||||20260207111500
PV2||||||||||||||||||||||||||||||||||||||||||20260207140000
DG1|1||I10^Essential (primary) hypertension^ICD-10-AM||20260207111500||F

Malaffi-Specific Requirements

• Emirates ID mandatory.
• Facility and provider identifiers must match DOH registry.
• ADHICS security controls: secure transport, audit logging, access control.

Acknowledgement Handling

Same pattern as NABIDH:

• Process ACK with MSA-1 status.
• Log and reconcile.

Error Handling

• Transport failures: same retry strategy as NABIDH.
• AE/AR: manual correction and resend.
• Compliance monitoring: KPI “NABIDH/Malaffi ADT Submission Rate” tracked from integration_message_log.

Retry and Recovery

Retry Strategy

• Trigger: MLLP/TLS transport failure or no ACK within 30 seconds.
• Non-retryable: ACK with AE or AR — route to DLQ for manual correction. DOH code-set errors specifically flagged for master data team.

Dead Letter Queue

• Storage: integration_message_log rows with status IN ('failed', 'rejected') and endpoint = 'MALAFFI'.
• Visibility: Integration Exceptions dashboard filtered by Malaffi endpoint; separate from NABIDH for independent monitoring.
• Retention: 90 days (regulatory compliance).
• Resolution workflow: Integration Admin reviews → corrects DOH facility/provider codes or data quality → triggers resend → status updated.
• Alerting: Email + dashboard alert if DLQ depth > 10 messages or any message aged > 24 hours. DOH may require notification if sustained outbound downtime exceeds their defined threshold.

Idempotency

• Deduplication key: MSH-10 (Message Control ID).
• Malaffi-side: Deduplicates by MSH-10.
• HIS-side: ACK matching via MSA-2 to integration_message_log.message_control_id.

Reconciliation

• Frequency: Daily at 03:30 (offset from NABIDH reconciliation).
• Process: Compare ADT events generated by Scheduling for Abu Dhabi facilities (facilities.emirate IN ('Abu Dhabi', 'Al Ain', 'Al Dhafra')) in the past 24 hours against integration_message_log entries with endpoint = 'MALAFFI' and status = 'acked'. Missing messages flagged for re-transmission.
• Report: Malaffi submission rate report (target >= 99.5%) on Integration dashboard and in daily operations report.
• KPI: Malaffi ADT Submission Rate tracked continuously alongside NABIDH.

Authentication & Security

All integrations must comply with:

• UAE PDPL (Federal Decree-Law No. 45/2021) for personal data protection.
• DHA NABIDH and DOH Malaffi security policies.
• ADHICS and TDRA/NESA cybersecurity standards.

Transport Security

• All external connections (NABIDH, Malaffi, portal) over HTTPS/TLS 1.2+ or MLLP over TLS.
• Internal APIs over mTLS within the hospital network.

mTLS Certificates

• Facility-specific client certificates issued by:
• DHA for NABIDH.
• DOH or approved CA for Malaffi.
• Certificates stored in secure keystore with rotation policies (at least annually or per regulator).

OAuth 2.0

• Patient Portal:
• Authorization Code + PKCE.
• Scopes: appointment.read, appointment.write, slot.read, patient.read.
• Internal service-to-service (e.g., CPOE, Billing):
• Client Credentials flow.
• Scopes per module (e.g., scheduling.write, encounter.read).

API Keys

• Not used for patient-facing flows.
• May be used for internal microservices where OAuth is not yet implemented, but must be:
• Stored securely (vault).
• Rotated regularly.

Message Encryption & Data Minimisation

• Only necessary fields included in each integration (data minimisation per PDPL).
• No sensitive clinical details (e.g., diagnoses) sent to Cleaning; only bed and priority.
• Logs and integration_message_log must mask Emirates ID and mobile numbers when viewed in non-admin UIs.

Audit & Monitoring

• All integration calls/messages logged with:
• Timestamp, source, target, user/service principal, outcome, correlation ID.
• Alerts:
• High failure rate (>1% in 15 minutes) for any integration.
• NABIDH/Malaffi submission rate below 99.5% over 24 hours.

Access Control

• Role-based access in HIS:
• Only integration services and designated admin roles can trigger resends or view full message payloads.
• Network segmentation:
• HIE connections via dedicated integration zone, firewalled from core clinical network.

This specification provides the developer-ready integration details for the Scheduling & Bed/OR Management module, aligned with UAE regulatory and HIE requirements.