Query for previous patient encounters
Query for a list of a specific patient’s previous encounters.
Transaction Specification
URL: GET /ws/rest/v1/patient/$<pat-ID>/encounters?$<queryParams>
Description: Queries a patient's previous encounters restricted to a specific time frame. This transaction return a list of encounters that fall within the query parameters or an error message in return if the transaction fails.
Request
The GET request may contain any combination of the query parameters however the pat-ID parameter is required.
Parameters
$<pat-ID>
This parameter represents the patient ID for the patient that the encounters must belong 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. GET /ws/rest/v1/patient/NID-1234567890123/encounters?$<queryParams>
$<queryParams>:
All query parameters are optional:
encounter_start_date
The start date for the SHR to start looking for records from. This parameter will be specified in the following date format:
yyyy-MM-dd'T'HH:mm:ss
See http://en.wikipedia.org/wiki/ISO_8601
encounter_end_date
The end date for the SHR to stop looking for records from. This parameter will be specified in the following date format:
yyyy-MM-dd'T'HH:mm:ss
See http://en.wikipedia.org/wiki/ISO_8601
Response
HTTP 200 - OK
The HTTP response body will contain an HL7 message that contains a list of all the encounters that match the given criteria.
Data
From Maternal data mapping.xls and RapidSMS_SHRIntegrationDraft.docx (PRE, RISK and BIR messages)
Message specification
The response body must contain a HL7 v2.5 ORU_R01 message that contain all of the patients encounters and observation restricted by the request parameters. The format is as follows:
See HL7 ORU_R01 structure
See Query-or-SavePatientEncounter
For more detail for RapidSMS:
Error
HTTP 500 - Server Error - If the server encountered an error.
HTTP 400 - Bad Request - If the parameters are malformed.
Orchestration
This section describes how this transaction is orchestrated through the HIM (interoperability layer) in order to complete this transaction.
- Call Get Enterprise Client ID to validate if client exists and to fetch ECID
- Call Query for previous patient encounters with ECID
- Replace references to ECID and EPID with NID or equivalent identifiers in response
Sample Messaging Implementation
Scenario 1
Query for a list of a specific patient’s previous encounters.
User Interface
TODO
Sample Request Message
GET https://hie.jembi.org:5000/ws/rest/v1/patient/NID-9876543210/encounters HTTP/1.1
Sample Response Message
<ORU_R01 xmlns="urn:hl7-org:v2xml"> <MSH> <MSH.1>|</MSH.1> <MSH.2>^~\&</MSH.2> <MSH.3> <HD.1>sendingApplication</HD.1> </MSH.3> <MSH.4> <HD.1>Shared Health Record</HD.1> </MSH.4> <MSH.5> <HD.1>receivingApplication</HD.1> </MSH.5> <MSH.6> <HD.1>Point of Care</HD.1> </MSH.6> <MSH.7> <TS.1>20120619153116</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>e8b79c87-46c8-42d1-a836-c302332a4c60</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> <ORU_R01.PATIENT_RESULT> <ORU_R01.PATIENT> <PID> <PID.1>1</PID.1> <PID.3> <CX.1>100</CX.1> <CX.5>CR_ID</CX.5> </PID.3> <PID.5> <XPN.1> <FN.1>Patient</FN.1> </XPN.1> </PID.5> <PID.7> <TS.1>19750101</TS.1> </PID.7> <PID.8>M</PID.8> <PID.11> <XAD.1> <SAD.1>555 Johnson Rd.</SAD.1> </XAD.1> <XAD.2>Apt. 555</XAD.2> <XAD.3>Indianapolis</XAD.3> <XAD.4>IN</XAD.4> <XAD.5>46202</XAD.5> </PID.11> <PID.30>false</PID.30> </PID> <NK1> <NK1.4> <XAD.1> <SAD.1>555 Johnson Rd.</SAD.1> <SAD.3>Apt. 555</SAD.3> </XAD.1> <XAD.3>Indianapolis</XAD.3> <XAD.4>IN</XAD.4> <XAD.5>46202</XAD.5> <XAD.6>USA</XAD.6> </NK1.4> </NK1> <ORU_R01.VISIT> <PV1> <PV1.1>1</PV1.1> <PV1.2>0</PV1.2> <PV1.3> <PL.1>1</PL.1> <PL.4> <HD.1>Unknown Location</HD.1> </PL.4> </PV1.3> <PV1.4>ADULTINITIAL</PV1.4> <PV1.7> <XCN.1>2</XCN.1> <XCN.2> <FN.1>Hornblower</FN.1> </XCN.2> <XCN.3>Horatio</XCN.3> </PV1.7> <PV1.19> <CX.1>1</CX.1> </PV1.19> <PV1.44> <TS.1>201206140214</TS.1> </PV1.44> </PV1> </ORU_R01.VISIT> </ORU_R01.PATIENT> <ORU_R01.ORDER_OBSERVATION> <ORC> <ORC.2> <EI.2>sendingApplication</EI.2> </ORC.2> <ORC.9> <TS.1>201206191531</TS.1> </ORC.9> <ORC.10> <XCN.1>1</XCN.1> <XCN.2> <FN.1>User</FN.1> </XCN.2> <XCN.3>Super</XCN.3> </ORC.10> <ORC.12> <XCN.1>2</XCN.1> <XCN.2> <FN.1>Hornblower</FN.1> </XCN.2> <XCN.3>Horatio</XCN.3> </ORC.12> <ORC.17> <CE.2>enteringOrganization</CE.2> </ORC.17> <ORC.21> <XON.1>orderingOrganization</XON.1> </ORC.21> </ORC> <OBR> <OBR.1>8</OBR.1> <OBR.3> <EI.1>1-univServiceId-20120429</EI.1> </OBR.3> <OBR.4> <CE.1>univServiceId</CE.1> <CE.2>univServIdName</CE.2> <CE.3>codeSys</CE.3> </OBR.4> <OBR.7> <TS.1>201204290117</TS.1> </OBR.7> <OBR.11>specimenActionCode</OBR.11> <OBR.16> <XCN.1>2</XCN.1> <XCN.2> <FN.1>Hornblower</FN.1> </XCN.2> <XCN.3>Horatio</XCN.3> </OBR.16> <OBR.25>resultStatus</OBR.25> <OBR.28> <XCN.1>2</XCN.1> <XCN.2> <FN.1>Hornblower</FN.1> </XCN.2> <XCN.3>Horatio</XCN.3> </OBR.28> </OBR> </ORU_R01.ORDER_OBSERVATION> <ORU_R01.ORDER_OBSERVATION> <ORC> <ORC.2> <EI.2>sendingApplication</EI.2> </ORC.2> <ORC.9> <TS.1>201206191531</TS.1> </ORC.9> <ORC.10> <XCN.1>1</XCN.1> <XCN.2> <FN.1>User</FN.1> </XCN.2> <XCN.3>Super</XCN.3> </ORC.10> <ORC.12> <XCN.1>2</XCN.1> <XCN.2> <FN.1>Hornblower</FN.1> </XCN.2> <XCN.3>Horatio</XCN.3> </ORC.12> <ORC.17> <CE.2>enteringOrganization</CE.2> </ORC.17> <ORC.21> <XON.1>orderingOrganization</XON.1> </ORC.21> </ORC> <OBR> <OBR.1>8</OBR.1> <OBR.3> <EI.1>2-univServiceId-20120429</EI.1> </OBR.3> <OBR.4> <CE.1>univServiceId</CE.1> <CE.2>univServIdName</CE.2> <CE.3>codeSys</CE.3> </OBR.4> <OBR.7> <TS.1>201204290117</TS.1> </OBR.7> <OBR.11>specimenActionCode</OBR.11> <OBR.16> <XCN.1>2</XCN.1> <XCN.2> <FN.1>Hornblower</FN.1> </XCN.2> <XCN.3>Horatio</XCN.3> </OBR.16> <OBR.25>resultStatus</OBR.25> <OBR.28> <XCN.1>2</XCN.1> <XCN.2> <FN.1>Hornblower</FN.1> </XCN.2> <XCN.3>Horatio</XCN.3> </OBR.28> </OBR> </ORU_R01.ORDER_OBSERVATION> <ORU_R01.ORDER_OBSERVATION> <ORC> <ORC.2> <EI.2>sendingApplication</EI.2> </ORC.2> <ORC.9> <TS.1>201206191531</TS.1> </ORC.9> <ORC.10> <XCN.1>1</XCN.1> <XCN.2> <FN.1>User</FN.1> </XCN.2> <XCN.3>Super</XCN.3> </ORC.10> <ORC.12> <XCN.1>2</XCN.1> <XCN.2> <FN.1>Hornblower</FN.1> </XCN.2> <XCN.3>Horatio</XCN.3> </ORC.12> <ORC.17> <CE.2>enteringOrganization</CE.2> </ORC.17> <ORC.21> <XON.1>orderingOrganization</XON.1> </ORC.21> </ORC> <OBR> <OBR.1>8</OBR.1> <OBR.3> <EI.1>3-univServiceId-20120614</EI.1> </OBR.3> <OBR.4> <CE.1>univServiceId</CE.1> <CE.2>univServIdName</CE.2> <CE.3>codeSys</CE.3> </OBR.4> <OBR.7> <TS.1>201206140214</TS.1> </OBR.7> <OBR.11>specimenActionCode</OBR.11> <OBR.16> <XCN.1>2</XCN.1> <XCN.2> <FN.1>Hornblower</FN.1> </XCN.2> <XCN.3>Horatio</XCN.3> </OBR.16> <OBR.25>resultStatus</OBR.25> <OBR.28> <XCN.1>2</XCN.1> <XCN.2> <FN.1>Hornblower</FN.1> </XCN.2> <XCN.3>Horatio</XCN.3> </OBR.28> </OBR> </ORU_R01.ORDER_OBSERVATION> <ORU_R01.ORDER_OBSERVATION> <ORC> <ORC.2> <EI.2>sendingApplication</EI.2> </ORC.2> <ORC.9> <TS.1>201206191531</TS.1> </ORC.9> <ORC.10> <XCN.1>1</XCN.1> <XCN.2> <FN.1>User</FN.1> </XCN.2> <XCN.3>Super</XCN.3> </ORC.10> <ORC.12> <XCN.1>2</XCN.1> <XCN.2> <FN.1>Hornblower</FN.1> </XCN.2> <XCN.3>Horatio</XCN.3> </ORC.12> <ORC.17> <CE.2>enteringOrganization</CE.2> </ORC.17> <ORC.21> <XON.1>orderingOrganization</XON.1> </ORC.21> </ORC> <OBR> <OBR.1>8</OBR.1> <OBR.3> <EI.1>4-univServiceId-20120614</EI.1> </OBR.3> <OBR.4> <CE.1>univServiceId</CE.1> <CE.2>univServIdName</CE.2> <CE.3>codeSys</CE.3> </OBR.4> <OBR.7> <TS.1>201206140214</TS.1> </OBR.7> <OBR.11>specimenActionCode</OBR.11> <OBR.16> <XCN.1>2</XCN.1> <XCN.2> <FN.1>Hornblower</FN.1> </XCN.2> <XCN.3>Horatio</XCN.3> </OBR.16> <OBR.25>resultStatus</OBR.25> <OBR.28> <XCN.1>2</XCN.1> <XCN.2> <FN.1>Hornblower</FN.1> </XCN.2> <XCN.3>Horatio</XCN.3> </OBR.28> </OBR> </ORU_R01.ORDER_OBSERVATION> <ORU_R01.ORDER_OBSERVATION> <ORC> <ORC.2> <EI.2>sendingApplication</EI.2> </ORC.2> <ORC.9> <TS.1>201206191531</TS.1> </ORC.9> <ORC.10> <XCN.1>1</XCN.1> <XCN.2> <FN.1>User</FN.1> </XCN.2> <XCN.3>Super</XCN.3> </ORC.10> <ORC.12> <XCN.1>2</XCN.1> <XCN.2> <FN.1>Hornblower</FN.1> </XCN.2> <XCN.3>Horatio</XCN.3> </ORC.12> <ORC.17> <CE.2>enteringOrganization</CE.2> </ORC.17> <ORC.21> <XON.1>orderingOrganization</XON.1> </ORC.21> </ORC> <OBR> <OBR.1>8</OBR.1> <OBR.3> <EI.1>5-univServiceId-20120614</EI.1> </OBR.3> <OBR.4> <CE.1>univServiceId</CE.1> <CE.2>univServIdName</CE.2> <CE.3>codeSys</CE.3> </OBR.4> <OBR.7> <TS.1>201206140214</TS.1> </OBR.7> <OBR.11>specimenActionCode</OBR.11> <OBR.16> <XCN.1>2</XCN.1> <XCN.2> <FN.1>Hornblower</FN.1> </XCN.2> <XCN.3>Horatio</XCN.3> </OBR.16> <OBR.25>resultStatus</OBR.25> <OBR.28> <XCN.1>2</XCN.1> <XCN.2> <FN.1>Hornblower</FN.1> </XCN.2> <XCN.3>Horatio</XCN.3> </OBR.28> </OBR> </ORU_R01.ORDER_OBSERVATION> <ORU_R01.ORDER_OBSERVATION> <ORC> <ORC.2> <EI.2>sendingApplication</EI.2> </ORC.2> <ORC.9> <TS.1>201206191531</TS.1> </ORC.9> <ORC.10> <XCN.1>1</XCN.1> <XCN.2> <FN.1>User</FN.1> </XCN.2> <XCN.3>Super</XCN.3> </ORC.10> <ORC.12> <XCN.1>2</XCN.1> <XCN.2> <FN.1>Hornblower</FN.1> </XCN.2> <XCN.3>Horatio</XCN.3> </ORC.12> <ORC.17> <CE.2>enteringOrganization</CE.2> </ORC.17> <ORC.21> <XON.1>orderingOrganization</XON.1> </ORC.21> </ORC> <OBR> <OBR.1>8</OBR.1> <OBR.3> <EI.1>6-univServiceId-20120614</EI.1> </OBR.3> <OBR.4> <CE.1>univServiceId</CE.1> <CE.2>univServIdName</CE.2> <CE.3>codeSys</CE.3> </OBR.4> <OBR.7> <TS.1>201206140214</TS.1> </OBR.7> <OBR.11>specimenActionCode</OBR.11> <OBR.16> <XCN.1>2</XCN.1> <XCN.2> <FN.1>Hornblower</FN.1> </XCN.2> <XCN.3>Horatio</XCN.3> </OBR.16> <OBR.25>resultStatus</OBR.25> <OBR.28> <XCN.1>2</XCN.1> <XCN.2> <FN.1>Hornblower</FN.1> </XCN.2> <XCN.3>Horatio</XCN.3> </OBR.28> </OBR> </ORU_R01.ORDER_OBSERVATION> <ORU_R01.ORDER_OBSERVATION> <ORC> <ORC.2> <EI.2>sendingApplication</EI.2> </ORC.2> <ORC.9> <TS.1>201206191531</TS.1> </ORC.9> <ORC.10> <XCN.1>1</XCN.1> <XCN.2> <FN.1>User</FN.1> </XCN.2> <XCN.3>Super</XCN.3> </ORC.10> <ORC.12> <XCN.1>2</XCN.1> <XCN.2> <FN.1>Hornblower</FN.1> </XCN.2> <XCN.3>Horatio</XCN.3> </ORC.12> <ORC.17> <CE.2>enteringOrganization</CE.2> </ORC.17> <ORC.21> <XON.1>orderingOrganization</XON.1> </ORC.21> </ORC> <OBR> <OBR.1>8</OBR.1> <OBR.3> <EI.1>7-univServiceId-20120614</EI.1> </OBR.3> <OBR.4> <CE.1>univServiceId</CE.1> <CE.2>univServIdName</CE.2> <CE.3>codeSys</CE.3> </OBR.4> <OBR.7> <TS.1>201206140214</TS.1> </OBR.7> <OBR.11>specimenActionCode</OBR.11> <OBR.16> <XCN.1>2</XCN.1> <XCN.2> <FN.1>Hornblower</FN.1> </XCN.2> <XCN.3>Horatio</XCN.3> </OBR.16> <OBR.25>resultStatus</OBR.25> <OBR.28> <XCN.1>2</XCN.1> <XCN.2> <FN.1>Hornblower</FN.1> </XCN.2> <XCN.3>Horatio</XCN.3> </OBR.28> </OBR> </ORU_R01.ORDER_OBSERVATION> <ORU_R01.ORDER_OBSERVATION> <ORC> <ORC.2> <EI.2>sendingApplication</EI.2> </ORC.2> <ORC.9> <TS.1>201206191531</TS.1> </ORC.9> <ORC.10> <XCN.1>1</XCN.1> <XCN.2> <FN.1>User</FN.1> </XCN.2> <XCN.3>Super</XCN.3> </ORC.10> <ORC.12> <XCN.1>2</XCN.1> <XCN.2> <FN.1>Hornblower</FN.1> </XCN.2> <XCN.3>Horatio</XCN.3> </ORC.12> <ORC.17> <CE.2>enteringOrganization</CE.2> </ORC.17> <ORC.21> <XON.1>orderingOrganization</XON.1> </ORC.21> </ORC> <OBR> <OBR.1>8</OBR.1> <OBR.3> <EI.1>8-univServiceId-20120614</EI.1> </OBR.3> <OBR.4> <CE.1>univServiceId</CE.1> <CE.2>univServIdName</CE.2> <CE.3>codeSys</CE.3> </OBR.4> <OBR.7> <TS.1>201206140214</TS.1> </OBR.7> <OBR.11>specimenActionCode</OBR.11> <OBR.16> <XCN.1>2</XCN.1> <XCN.2> <FN.1>Hornblower</FN.1> </XCN.2> <XCN.3>Horatio</XCN.3> </OBR.16> <OBR.25>resultStatus</OBR.25> <OBR.28> <XCN.1>2</XCN.1> <XCN.2> <FN.1>Hornblower</FN.1> </XCN.2> <XCN.3>Horatio</XCN.3> </OBR.28> </OBR> </ORU_R01.ORDER_OBSERVATION> </ORU_R01.PATIENT_RESULT> </ORU_R01>