Save Patient Encounter
This transaction deals with saving a patient's encounter in their medical record. The save message should be able to contain information for all the RHEA supported forms as well as information received from the RapidSMS application. This information should all be stored as observations in the SHR.
Transaction Specification
URL: POST /ws/rest/v1/patient/$<pat-ID>/encounters
Description: This transaction deals with saving a patient's encounter in their medical record. The save message should be able to contain information for all the RHEA supported forms as well as information received from the RapidSMS application. This information should all be stored as observations in the SHR.
Request
HTTP request body will contain the HL7 v2.5 message defined below with a single patient identification parameter in the URL
Parameters:
$<pat-ID>
This parameter represents the patient ID for the patient that the encounter belongs to. It must be specified in the following format:
<ID-type>-<ID-number>
Where <ID-type> is one of the following:
- NID - for a national identification number
- MUT - Mutuelle number
- RAM - Rama number
- OMRS<fosaid of facility> - OpenMRS identifier eg, OMRS357-123456789
Eg. POST /ws/rest/v1/patient/NID-1234567890123/encounters
Data
From Maternal Data and Requirements for RapidSMS_SHR Integration FINAL.docx (PRE, RISK and BIR messages)
Message specification
The body must contain a HL7 v2.5 ORU_R01 message with the following structure:
See HL7 ORU_R01 structure
See Query-or-SavePatientEncounter for message mappings
For more detail for RapidSMS:
Response
HTTP 201 - Created - If the encounter was saved.
The location (URI) of the newly created resource should be returned in the location header.
Error
HTTP 500 - Server Error - If the server encountered an error.
HTTP 400 - Bad Request - If the HL7 v2.5 message is malformed.
Orchestration
This section describes how this transaction is orchestrated through the HIM (interoperability layer) in order to complete this transaction.
- Verify transaction identifiers
- Call Get Enterprise Client ID to validate if client exists
- Call Get Enterprise Provider ID to validate is provider exists
- Call Get HC Facility to validate if the facility exists
- Verify that coded used are valid.
- Call Verify Code to verify terminology
- If the identifiers and terms check out
- Enrich transaction to contain ECID and EPID
- Call Save Patient Encounter
- Else
- Send transaction to error queue
Sample Messaging Implementation
Scenario 1
At the OpenMRS Point-of-Care system, the user fills out one of the seven HTML forms. Once the encounter (i.e. form) is saved to the local OpenMRS database, the system will automatically (in the backend) create an ORU_RO1 message and attempt to send this to the Shared Health Record. If the internet is down, this message will be queued and a scheduled service will periodically attempt to re-send the message when the internet is available. This scenario shows an ANC Physical Exam Form being saved.
ANC Physical Exam Form
Data
@Ishimwe - make a copy of the query-or-save excel spreadsheet, add a column to it for the sample data, and add it here.
Request Message and Body
POST https://localhost:5000/ws/rest/v1/patient/NID-123456789/encounters HTTP/1.1
<?xml version="1.0"?>
<ORU_R01 xmlns="urn:hl7-org:v2xml">
<MSH>
<MSH.1>|</MSH.1>
<MSH.2>^~\&</MSH.2>
<MSH.4>
<HD.1>357</HD.1>
</MSH.4>
<MSH.6>
<HD.1>Shared Health Record</HD.1>
</MSH.6>
<MSH.7>
<TS.1>20120709174213</TS.1>
</MSH.7>
<MSH.9>
<MSG.1>ORU</MSG.1>
<MSG.2>R01</MSG.2>
<MSG.3>ORU_R01</MSG.3>
</MSH.9>
<MSH.10>a349277e-116c-4663-a222-1abe200c2113</MSH.10>
<MSH.11>
<PT.1>D</PT.1>
<PT.2>C</PT.2>
</MSH.11>
<MSH.12>
<VID.1>2.5</VID.1>
<VID.2>
<CE.1>RWA</CE.1>
</VID.2>
</MSH.12>
<MSH.21>
<EI.1>CLSM_V0.83</EI.1>
</MSH.21>
</MSH>
<ORU_R01.PATIENT_RESULT>
<ORU_R01.PATIENT>
<PID>
<PID.1>1</PID.1>
<PID.3>
<CX.1>dc8d2234-7fce-4869-945e-97c8b7d97332</CX.1>
<CX.5>Rwanda National ID</CX.5>
</PID.3>
<PID.5>
<XPN.1>
<FN.1>Patient</FN.1>
</XPN.1>
<XPN.2>Mosa</XPN.2>
</PID.5>
</PID>
<ORU_R01.VISIT>
<PV1>
<PV1.2>0</PV1.2>
<PV1.3>
<PL.1>103</PL.1>
<PL.4>
<HD.1>Rwamagana</HD.1>
</PL.4>
</PV1.3>
<PV1.4>ANC</PV1.4>
<PV1.7>
<XCN.1>3525410</XCN.1>
<XCN.2>
<FN.1>Doctor</FN.1>
</XCN.2>
<XCN.3>John</XCN.3>
<XCN.13>NID</XCN.13>
</PV1.7>
<PV1.44>
<TS.1>201207090542</TS.1>
</PV1.44>
</PV1>
</ORU_R01.VISIT>
</ORU_R01.PATIENT>
<ORU_R01.ORDER_OBSERVATION>
<ORC>
<ORC.1>RE</ORC.1>
<ORC.9>
<TS.1>201207091742</TS.1>
</ORC.9>
<ORC.12>
<XCN.1>7</XCN.1>
</ORC.12>
<ORC.16>
<CE.1>XXX</CE.1>
<CE.2>YYY</CE.2>
<CE.3>ZZZ</CE.3>
</ORC.16>
</ORC>
<OBR>
<OBR.1>0</OBR.1>
<OBR.3>
<EI.1>77</EI.1>
</OBR.3>
<OBR.4>
<CE.2>ANC</CE.2>
</OBR.4>
<OBR.7>
<TS.1>201207090000</TS.1>
</OBR.7>
<OBR.16>
<XCN.1>7</XCN.1>
<XCN.2>
<FN.1>Doctor</FN.1>
</XCN.2>
<XCN.3>John</XCN.3>
</OBR.16>
<OBR.20>103</OBR.20>
<OBR.21>Rwamagana</OBR.21>
</OBR>
</ORU_R01.ORDER_OBSERVATION>
<ORU_R01.ORDER_OBSERVATION>
<OBR>
<OBR.1>1</OBR.1>
<OBR.18>0</OBR.18>
<OBR.29>
<EIP.2>
<EI.3>77</EI.3>
</EIP.2>
</OBR.29>
</OBR>
<ORU_R01.OBSERVATION>
<OBX>
<OBX.1>0</OBX.1>
<OBX.2>NM</OBX.2>
<OBX.3>
<CE.1>1279</CE.1>
<CE.2>NUMBER OF WEEKS PREGNANT</CE.2>
<CE.3>PIH</CE.3>
</OBX.3>
<OBX.5>34.0</OBX.5>
<OBX.6>
<CE.1>weeks</CE.1>
<CE.3>UCUM</CE.3>
</OBX.6>
<OBX.14>
<TS.1>20120709174208</TS.1>
</OBX.14>
</OBX>
</ORU_R01.OBSERVATION>
<ORU_R01.OBSERVATION>
<OBX>
<OBX.1>1</OBX.1>
<OBX.2>NM</OBX.2>
<OBX.3>
<CE.1>5088</CE.1>
<CE.2>TEMPERATURE (C)</CE.2>
<CE.3>PIH</CE.3>
</OBX.3>
<OBX.5>34.0</OBX.5>
<OBX.6>
<CE.1>DEG C</CE.1>
<CE.3>UCUM</CE.3>
</OBX.6>
<OBX.14>
<TS.1>20120709174208</TS.1>
</OBX.14>
</OBX>
</ORU_R01.OBSERVATION>
<ORU_R01.OBSERVATION>
<OBX>
<OBX.1>2</OBX.1>
<OBX.2>NM</OBX.2>
<OBX.3>
<CE.1>5089</CE.1>
<CE.2>WEIGHT (KG)</CE.2>
<CE.3>PIH</CE.3>
</OBX.3>
<OBX.5>34.0</OBX.5>
<OBX.6>
<CE.1>kg</CE.1>
<CE.3>UCUM</CE.3>
</OBX.6>
<OBX.14>
<TS.1>20120709174208</TS.1>
</OBX.14>
</OBX>
</ORU_R01.OBSERVATION>
<ORU_R01.OBSERVATION>
<OBX>
<OBX.1>3</OBX.1>
<OBX.2>NM</OBX.2>
<OBX.3>
<CE.1>5086</CE.1>
<CE.2>DIASTOLIC BLOOD PRESSURE</CE.2>
<CE.3>PIH</CE.3>
</OBX.3>
<OBX.5>34.0</OBX.5>
<OBX.6>
<CE.1>mmHg</CE.1>
<CE.3>UCUM</CE.3>
</OBX.6>
<OBX.14>
<TS.1>20120709174208</TS.1>
</OBX.14>
</OBX>
</ORU_R01.OBSERVATION>
<ORU_R01.OBSERVATION>
<OBX>
<OBX.1>4</OBX.1>
<OBX.2>NM</OBX.2>
<OBX.3>
<CE.1>123</CE.1>
<CE.2>Length of the uterus (fundal height) in cm</CE.2>
<CE.3>local</CE.3>
</OBX.3>
<OBX.5>34.0</OBX.5>
<OBX.6>
<CE.1>cm</CE.1>
<CE.3>UCUM</CE.3>
</OBX.6>
<OBX.14>
<TS.1>20120709174208</TS.1>
</OBX.14>
</OBX>
</ORU_R01.OBSERVATION>
<ORU_R01.OBSERVATION>
<OBX>
<OBX.1>5</OBX.1>
<OBX.2>NM</OBX.2>
<OBX.3>
<CE.1>5085</CE.1>
<CE.2>SYSTOLIC BLOOD PRESSURE</CE.2>
<CE.3>PIH</CE.3>
</OBX.3>
<OBX.5>34.0</OBX.5>
<OBX.6>
<CE.1>mmHg</CE.1>
<CE.3>UCUM</CE.3>
</OBX.6>
<OBX.14>
<TS.1>20120709174208</TS.1>
</OBX.14>
</OBX>
</ORU_R01.OBSERVATION>
</ORU_R01.ORDER_OBSERVATION>
</ORU_R01.PATIENT_RESULT>
</ORU_R01>
Request Response
No body response is returned, only HTTP_CODE describe the status of the transaction.