DRAFT PH Road Safety Implementation Guide
0.1.0 - ci-build Philippines flag

DRAFT PH Road Safety Implementation Guide, published by UP Manila - National Institutes of Health - National Telehealth Center. This guide is not an authorized publication; it is the continuous build for version 0.1.0 built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/UPM-NTHC/PH-RoadSafetyIG/ and changes regularly. See the Directory of published versions

Usecase

This page contains navigable use-case diagrams (Mermaid) that help implementers and integrators follow the common workflows in the Road Safety MDS: EMS run-report submission, Facility retrieval and intake, and optional Eligibility workflows.

Notes on diagrams

  • These diagrams are authored in Mermaid syntax so they render in the IG HTML output where Mermaid is supported.
  • Use the diagrams to trace the happy path and alternative branches for each use case. Each node maps to an actionable step (API call, bundle composition, or policy decision).

High level Overview

Road Safety Data Exchange - High-Level OverviewRoad Safety Data Exchange - High-Level OverviewScene to FacilityEMSHealth Data GatewayFacility EHRONEISS APIDPWH/DOTrHealth CenterEMSEMSHealth Data GatewayHealth Data GatewayFacility EHRFacility EHRONEISS APIONEISS APIDPWH/DOTrDPWH/DOTrHealth CenterHealth CenterCentral gateway (ONEISS / NHDR)Routes, checks, and shares recordsSupports Subscription delivery to ETLScene capture:- Incident/Encounter- Patient- Vitals & notes- Run Report form/attachmentsScene to EMS Transport ReportingSend Run Report(Incident + Patient + Vitals + Attachments)Confirm receipt(Incident reference)Prefill triage and handoff usingincident and vitals from EMSFacility[Retrieval]Retrieve Incident & Patient SummaryProvide Summary(Encounter + Patient snapshot)[Submission]Share Facility Care Update(Triage, diagnoses, procedures)Update confirmedONEISS ETL (optional)Subscription notification (POST /notifications)Transform to ONEISS compatible data[Alternative]Scheduled push of reports in ONEISS Compatible DataOr Manual export of reportsAgency ReportingRequest Agency ReportProvide Report(Required reporting fields)Follow-up CareRequest Patient/Encounter for follow-upProvide Care Continuity DataKey concepts- Encounter connects EMS scene and Facility care- Patient identity is shared across systems- Observations & Documents add clinical detail- Organization identifies EMS, Facilities, and Agencies- ETL can subscribe/pull/transform data for reporting

Low level Overview

Road Safety Data Exchange - Central FHIR ServerRoad Safety Data Exchange - Central FHIR ServerScene to FacilityEMSFHIR GatewayFacility EHRONEISS APIDPWH/DOTrHealth CenterEMSEMSFHIR GatewayFHIR GatewayFacility EHRFacility EHRONEISS APIONEISS APIDPWH/DOTrDPWH/DOTrHealth CenterHealth CenterONEISS / NHDRFHIR ServerSupports Subscription delivery to ETLScene to EMS Transport ReportingEMS* (Electronic Reporting system)POST Bundle.runreport(Encounter.transport-runreport + resources)201 Created (Encounter id)Validate & indexFacility[Retrieval]Facility EHR (iHOMIS / other EHR)GET /Encounter?identifier=IncidentNo|<system>|<value>200 Bundle (Encounter + subject)GET /Observation?encounter={id}&category=vital-signs200 Bundle (Vitals at scene)GET /DocumentReference?context-encounter={id}200 Bundle (Run form, attachments)Prefill triage, vitals, timestamps, crew handoff notes[Submission]POST Bundle.facility(Encounter + clinical resources)201 CreatedONEISS ETL (Subscription)[Hook based]POST /notifications (Subscription delivery)Transform 200 /SOAP Bundle (facility submission)201 Created[Alternative (Scheduled or Manual Trigger)]POST /SOAP Bundle (transformed/normalized) every X seconds201 CreatedAgency ReportingDPWH/DOTr (Agency reporting system)GET /Encounter?service-provider=Org/{id}&...200 Bundle (relevant agency report data)Follow-up CareHealth centers (iClinicSys, or other private EHR)GET /Patient/{id} or /Encounter?patient={id}200 Bundle (patient/encounter data)Key concepts- Presence of a ONEISS / NHDR central FHIR gateway- Bundles carry Encounter, Observations, Documents- Systems retrieve or submit via standard FHIR endpoints- ETL subscribes to transform and normalize data for reporting

ONEISS and NHDR can be run as a single FHIR server. EMS posts run-report Bundles to that server, facilities and agencies query the same endpoint, and updates are posted back so everyone sees a consistent record.

Actors

  • EMS: ambulance/run-reporting app that sends the initial Bundle.runreport.
  • FHIR server: unified ONEISS + NHDR endpoint that validates, stores, indexes, and serves queries.
  • Facility EHR: looks up incidents and fetches related resources to prefill intake.
  • DPWH/DOTr (agency): queries encounters for reporting.
  • Health centers: query patient/encounter history for follow-up.

Key use-cases (one-line)

  • UC1: EMS POST Bundle.runreport → server validates, stores, returns 201 + Encounter.id.
  • UC2: Facility GET /Encounter?identifier={IncidentNo} → server returns Encounter Bundle.
  • UC3/4: Facility POST updated Bundle/Encounter → server stores updates and makes them discoverable.
  • UC5: Agency GET /Encounter (or reports) → server returns 200 Bundles for reporting.
  • UC6: Health center GET /Patient or /Encounter → server returns patient history for follow-up.

Quick implementation tips

  • Return clear OperationOutcome (4xx/422) on validation errors; consider 'accept but quarantine' for non-critical warnings.
  • Use a stable IncidentNo / Encounter.identifier and idempotency keys to avoid duplicates.
  • Secure APIs with OAuth2/SMART scopes, log/audit access, and protect sensitive attachments.
  • Support Subscriptions for push notifications or simple polling for facility notifications; use paging for large result sets.

When to choose unified vs split

  • Unified server: simpler operations and discovery (single endpoint to secure and scale).
  • Gateway + NHDR split: use when you need a separate ingest/validation layer for quarantining, policy enforcement, or staged acceptance workflows.

b EMS ↔ FHIR ↔ Facility (cropped)

Road Safety Data Exchange - Scene to Facility EHRRoad Safety Data Exchange - Scene to Facility EHREMSFHIR GatewayFacility EHRONEISS APIEMSEMSFHIR GatewayFHIR GatewayFacility EHRFacility EHRONEISS APIONEISS APIONEISS / NHDR FHIR Server(gateway) — supports Subscription delivery to ETLScene to EMS Transport ReportingEMS* (Electronic Reporting system)POST Bundle.runreport(Encounter.transport-runreport + Observations + DocumentReference)201 Created (Encounter id)Validate & indexFacility[Retrieval]Facility EHR (iHOMIS / other EMR)GET /Encounter?identifier=IncidentNo|{system}|{value}200 Bundle (Encounter + subject)GET /Observation?encounter={Encounter/id}&category=vital-signs200 Bundle (Vitals at scene)GET /DocumentReference?context-encounter={Encounter/id}200 Bundle (Run form, attachments)Prefill intake form (triage, vitals, timestamps, handoff notes)[Submission]POST Bundle.facility(Encounter + clinical resources)201 CreatedONEISS ETL (Subscription)[Hook based]ONEISS ETL subscribes to relevant events on the FHIR Gateway(e.g. Encounter updates, Bundle.facility submissions) and pullresources referenced by notification.POST /notifications (Subscription delivery)200 OKAfter transformation of the bundle, ETL returns a SOAP format API call to ONEISS.GET /Encounter?identifier=IncidentNo|{system}|{value}200 Bundle (raw run-report + facility submission)[Alternative (Scheduled or Manual Trigger)]ETL may just loop api calls looking for changesor new submissions or by button trigger.POST /SOAP ONEISS (transformed/normalized)201 CreatedKey concepts- EMS submits run reports to ONEISS/NHDR (FHIR Gateway)- Facility systems retrieve scene data (Encounters, Observations, Documents)- ONEISS ETL subscribes to Gateway notifications and can pull or accept pushed content- Use standard FHIR endpoints and Bundles for exchange

Brief summary

This cropped diagram focuses on the three-party interaction most implementers need to implement first:

  • EMS posts the run-report bundle to the FHIR endpoint (UC1).
  • The facility EHR retrieves the encounter and related resources to prefill intake (UC2).
  • The facility posts its intake/clinical bundle back to the same FHIR server (UC3/4).

EMS decision flow (submit/update/cancel)

EMS POST Bundle.runreportGateway validates?YesNoStore Bundle, index by Incident No.EMS POST updated Bundle.runreportwith same Encounter.identifierYesDoes EMS update the run report later?No:DoneEMS POST Task or Bundle with cancel flagYesIs cancellation needed?No:DoneReturn OperationOutcome 4xx/422

How the decision flow works

When EMS submits a run report, the gateway validates and stores it. If validation fails, the gateway returns an error describing what to fix. If validation succeeds, the bundle is stored and indexed so the hospital can find it later.

EMS may later submit updates (for example to correct timestamps or add missing data) using the same Encounter identifier. If the incident is cancelled (e.g., a false alarm), EMS should send a cancellation task or a flagged bundle and the gateway should mark the record accordingly.

Quick links

  • Retrieve Encounter by Incident No.
  • Fetch Observations by Encounter
  • Fetch DocumentReference for run form

Recommended API calls (illustrative):

  • GET /Encounter?identifier=IncidentSystem {incidentNo}&_include=Encounter:subject&_revinclude=Observation:encounter&_revinclude=DocumentReference:encounter
  • GET /Observation?encounter={Encounter/id}&category=vital-signs
  • GET /DocumentReference?context-encounter={Encounter/id}

Example: see runreport-bundle.json for a Bundle.runreport example.

Facility retrieval alternatives

Facility EHR arrivesDo they have Incident No.?YesNoGET /Encounter?identifier=IncidentSystem|value&_include=Encounter:subject&_revinclude=Observation:encounterEncounter found?YesNoGET related resources or use $everythingSearch by time window + demographicsSearch by time window + demographicsSingle match?YesNoFetchAllManual reconcile by staff(Optional) NotificationsSubscribe (criteria: Encounter.class=AMB & service-provider=Org/<id>)On create -> notify facility

If the facility cannot find the incident by identifier

Start by searching with the Incident Number. If that lookup doesn’t return a match, try searching by the approximate time window and patient demographics to find likely matches. If several likely matches appear or confidence is low, present a clear manual reconciliation step for staff to choose the correct record. Subscriptions are optional but useful — they let facilities get a notification automatically when matching encounters arrive.

how the receiving facility retrieves EMS run report data, reconciles patients, and submits the Facility bundle (Bundle.facility) to the ONEISS gateway. It includes guidance on referencing the EMS Encounter, mapping diagnoses, and handling attachments.

Key steps

  1. Retrieve the transport Encounter and related resources using Incident No.
  2. Prefill local chart fields and reconcile patient identity
  3. Create Encounter.facility and supporting Condition/Observation resources
  4. Submit Bundle.facility to the gateway (transaction or collection)

ONEISS ETL — Subscription workflow & mock script

This section describes how an internal/external ETL service ONEISS API could hypothetically subscribe to events on the FHIR Gateway to pull or receive pushed run-report and facility-submission data, and map it to their respective stake holders.

ONEISS ETL — Gateway ↔ ONEISS Subscription WorkflowONEISS ETL — Gateway ↔ ONEISS Subscription WorkflowFHIR GatewayETL ScriptONEISS APIFHIR GatewayFHIR GatewayETL ScriptETL ScriptONEISS APIONEISS APIGateway hosts Subscription resourcesand delivers notifications to Script EndpointSubscription deliveryPOST /notifications (Subscription delivery)200 OKNotification may include resource references orinline resources (application/fhir+json).ETL Script may choose to pull full resources after notify.Pull & TransformGET /Encounter?identifier=IncidentNo|{system}|{value}200 Bundle (raw EMS + Facility data) (transformed / normalized)POST /SOAP (transformed / normalized)201 CreatedExample interactions:- Subscription.delivery: HTTP POST to ETL endpoint with content-type application/fhir+json- ETL Script can pull resources using standard GET queries or accept pushed content Operational notes:- Secure endpoints (OAuth2 client credentials or mTLS)- Support retries, backoff, and dead-letter handling on the Gateway- Agree transformation rules, canonical mappings, and provenance

How it works (high level)

  • Provision a Subscription resource on the Gateway with criteria (for example: Encounter updates or Bundle.facility submissions scoped to specific service-provider or organization).
  • The Gateway delivers notifications to the ETL endpoint (HTTP POST with application/fhir+json). Notifications may include resource snippets or references.
  • On notification the ETL may either pull full resources via GET queries, or accept the pushed content and perform transform/enrichment.
  • After transformation the ETL POSTs a normalized Bundle back to the Gateway (POST /Bundle) or uses an agreed process operation (e.g. $process-message) so the transformed data becomes authoritative for reporting.

Mock script outline (example - for reference only)

  • Subscribe: POST /Subscription {criteria: "Encounter?service-provider=Org/{id}", endpoint: "https://etl.example.org/notify"}
  • On notify (ETL endpoint): 1) Validate signature and auth on incoming notification 2) If payload includes resources, extract identifiers; else call GET /Encounter?identifier=… 3) Transform: map local codes to canonical CodeSystems, normalize timestamps, deduplicate patient references 4) POST transformed Bundle to Gateway: POST /Bundle (or call $process-message)

Caveats and governance

  • The mock script is an illustrative starting point — adoption requires formal agreements, ongoing maintenance, and security provisioning (OAuth2/mTLS, retry/backoff, DLQ handling).
  • Transformation rules, canonical mappings, and provenance policies must be agreed and versioned.
  • There is no guarantee of compatibility without integration testing and operational support.