Message specifications for the ICT4H demo

Owned by Ryan Crichton
Last updated: Sept 19, 2013 by Hannes Venter (Unlicensed)

In order to perform an identification of a pregnant women, the mobile server will have to make 2 calls to the HIE:

  1. A patient registration message with some basic demographics
  2. A save encounter message
    1. with the observation of 'suspected pregnancy' or,
    2. with the observation of 'confirmed pregnancy'.

Please note for the use case to work in the demo, you must send a registration message first and then the encounter message.

Below are the message specifications for each of these. We are using HL7v2 for each of these message formats, but we are using the XML representation rather than the more typical ER7 format. This is because the OpenHIM has a restful interface, so it makes more sense to send XML.

Workflow details

  1. A CHW arrives at a village, the CHW identifies that a women whom she suspects is pregnant and uses a mobile application (e.g. Cell-life Connect mobile application) to capture this suspected pregnancy registration.
  2. The CHW enters the women's name, date of birth, ID-Number, last mensuration date and the pregnancy status (suspected | confirmed) in to the mobile phone and sends this message to the mobile application server
  3. The mobile application server receives this information and stores it
  4. The mobile server then sends this information on to the health information exchange (HIE) infrastructure by doing the following:
    1. The mobile server must register the patient before observation can be sent so a register patient message is generated and sent to the HIE 
    2. Once the register message has been successfully saved (HTTP 201 response) then the mobile server generates a message indicating if the pregnancy is suspected or confirmed and sends this to the HIE
    3. Once a successful response (HTTP 201 response) is received from the HIE infrastructure the workflow is complete.

 

ICT4H Endpoint details

HIM: https://test.jembi.org:5000

Http basic auth details:

  • user: test
  • password: test

The self signed cert is attached

Identification (register patient) message

POST /ws/rest/v1/patients/

Data elements needed

  • Time stamp for now - ${now} - eg. "20120918160235" (yyyyMMddhhmmss)
  • Given name - ${given_name} - eg. "Mosa"
  • Family name - ${family_name} - eg. "Patient"
  • Date of birth - ${dob} - eg. "19910405"
  • Gender - ${gender} - eg. "F"
  • ID Number - ${nid} - eg. "1234567890123456" (note this must be a 16 digit number due to some of the code we are using for the demo coming from the our Rwanda work where id numbers are 16 digits)

Responses:

201 - patient created

304 - patient already exists

Message Template:

POST body 
<ADT_A05 xmlns="urn:hl7-org:v2xml">
   <MSH>
      <MSH.1>|</MSH.1>
      <MSH.2>^~\&amp;</MSH.2>
      <MSH.7>
         <TS.1>${now}</TS.1>
      </MSH.7>
      <MSH.9>
         <MSG.1>ADT</MSG.1>
         <MSG.2>A28</MSG.2>
         <MSG.3>ADT_A05</MSG.3>
      </MSH.9>
      <MSH.12>
         <VID.1>2.5</VID.1>
      </MSH.12>
   </MSH>
   <PID>
      <PID.3>
         <CX.1>${nid}</CX.1>
         <CX.5>NID</CX.5>
      </PID.3>
      <PID.5>
         <XPN.1>
            <FN.1>${family_name}</FN.1>
         </XPN.1>
         <XPN.2>${given_name}</XPN.2>
      </PID.5>
      <PID.7>
         <TS.1>${dob}</TS.1>
      </PID.7>
      <PID.8>${gender}</PID.8>
   </PID>
   <NK1>
      <NK1.1>1</NK1.1>
      <NK1.2>
         <XPN.1>
            <FN.1></FN.1>
         </XPN.1>
      </NK1.2>
      <NK1.3>
         <CE.1>MTH</CE.1>
         <CE.2>mother</CE.2>
         <CE.3>REL_RTS</CE.3>
      </NK1.3>
   </NK1>
   <NK1>
      <NK1.1>2</NK1.1>
      <NK1.2>
         <XPN.1>
            <FN.1></FN.1>
         </XPN.1>
      </NK1.2>
      <NK1.3>
         <CE.1>FTH</CE.1>
         <CE.2>father</CE.2>
         <CE.3>REL_RTS</CE.3>
      </NK1.3>
   </NK1>
</ADT_A05>

Message body specification: Register-or-Query-Client

More transaction details: Register new patient

Save encounter message

POST /ws/rest/v1/patient/$<pat-ID>/encounters

where $<pat-ID> is the string: "NID-" + the_patients_national_Id

Data elements needed

  • Time stamp for now - ${now} - eg. "20120918160235" (yyyyMMddhhmmss)
  • Given name - ${given_name} - eg. "Mosa"
  • Family name - ${family_name} - eg. "Patient"
  • Date of birth - ${dob} - eg. "19910405"
  • ID Number - ${nid} - eg. "1234567890123456" (note this must be a 16 digit number due to some of the code we are using for the demo coming from the our Rwanda work where id numbers are 16 digits)
  • The pregnancy status observation
    • Text name - ${obs_name} - This will be "Pregnancy, not (yet) confirmed" or "Pregnancy confirmed"
    • Code - ${obs_code} - For not confirmed this will be "Z32.0" for confirmed this will be "Z32.9"

Responses:

201 - encounter saved

Message template:

POST body 
<?xml version="1.0"?>
<ORU_R01 xmlns="urn:hl7-org:v2xml">
    <MSH>
        <MSH.1>|</MSH.1>
        <MSH.2>^~\&amp;amp;</MSH.2>
        <MSH.4>
            <HD.1>363</HD.1>
        </MSH.4>
        <MSH.6>
            <HD.1>Shared Health Record</HD.1>
        </MSH.6>
        <MSH.7>
            <TS.1>${now}</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>63357449-6a6c-4faa-af7a-e8843a545c31</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.3>
                    <CX.1>${nid}</CX.1>
                    <CX.5>NID</CX.5>
                </PID.3>
                <PID.5>
                    <XPN.1>
                        <FN.1>${family_name}</FN.1>
                    </XPN.1>
                    <XPN.2>${given_name}</XPN.2>
                </PID.5>
                <PID.7>
                	<TS.1>${dob}</TS.1>
                </PID.7>
            </PID>
            <ORU_R01.VISIT>
                <PV1>
                    <PV1.2>0</PV1.2>
                    <PV1.3>
                        <PL.1>111</PL.1>
                        <PL.4>
                            <HD.1>Ruhunda</HD.1>
                        </PL.4>
                    </PV1.3>
                    <PV1.4>ANC OB and Past Medical History</PV1.4>
                    <PV1.7>
						<XCN.1>3525410</XCN.1>
						<XCN.2>
							<FN.1>Developer</FN.1>
						</XCN.2>
						<XCN.3>Jembi</XCN.3>
						<XCN.13>NID</XCN.13>
					</PV1.7>
                    <PV1.44>
                        <TS.1>${now}</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>${now}</TS.1>
                </ORC.9>
                <ORC.12>
                    <XCN.1>3525410</XCN.1>
                </ORC.12>
                <ORC.16>
                    <CE.1>Identifier</CE.1>
                    <CE.2>Text</CE.2>
                    <CE.3>Name of Coding System</CE.3>
                </ORC.16>
            </ORC>
            <OBR>
                <OBR.1>0</OBR.1>
                <OBR.3>
                    <EI.1>1437</EI.1>
                </OBR.3>
                <OBR.4>
                    <CE.2>ANC OB and Past Medical History</CE.2>
                </OBR.4>
                <OBR.7>
                    <TS.1>${now}</TS.1>
                </OBR.7>
                <OBR.20>111</OBR.20>
                <OBR.21>Ruhunda</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>1437</EI.3>
                    </EIP.2>
                </OBR.29>
            </OBR>
            <ORU_R01.OBSERVATION>
                <OBX>
                    <OBX.1>0</OBX.1>
                    <OBX.2>CE</OBX.2>
                    <OBX.3>
                        <CE.1>${obs_code}</CE.1>
                        <CE.2>${obs_name}</CE.2>
                        <CE.3>ICD10</CE.3>
                    </OBX.3>
                    <OBX.5>
                        <CE.1>1065</CE.1>
                        <CE.2>YES</CE.2>
                        <CE.3>RWCS</CE.3>
                    </OBX.5>
                    <OBX.14>
                        <TS.1>${now}</TS.1>
                    </OBX.14>
                </OBX>
            </ORU_R01.OBSERVATION>
        </ORU_R01.ORDER_OBSERVATION>
    </ORU_R01.PATIENT_RESULT>
</ORU_R01>

Message body specification: Query-or-SavePatientEncounter

More transaction details: Save Patient Encounter