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:

See RapidSMSMessaging Specs

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.

  1. Call Get Enterprise Client ID to validate if client exists and to fetch ECID
  2. Call Query for previous patient encounters with ECID
  3. 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>^~\&amp;</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>