PDQ-HPRS ITI integration documentation

Supporting Information

• ITI-21 Examples
• Supported Identifiers
• PID segment Definition
• Table0203
• Table0363
• Table 0445
• Article Sources and Contributors
• Table0002
• MPI name search implementation
• Important Links: HL7

ITI-21 Examples

ITI-21 request with what domains returned

Request

MSH|^~\&|TEST_HARNESS|TEST|CR1|MOH_CAAT|20090226131520-0600||QBP^Q22^QBP_Q21|TEST-CR-14-30|P|2.5
QPD|Q22^Find Candidates^HL7|8494764101303661668890645833527|@PID.3.1^20287~@PID.3.4.1^DOH_fileNumber.172842~@PID.3.4.2^2.25.17843963144693579256192190624330832718.172842~@PID.3.4.3^ISO|||||^^^DHA~^^^HPRS_PATIENT_UUID
RCP|I

Response

MSH|^~\&|HPRSPIXMANAGER^2.25.17843963144693579256192190624330832714^ISO|HPRSPIXMANAGER^2.25.17843963144693579256192190624330832714^ISO|TEST_HARNESS^UNKNOWN^ISO|TEST^UNKNOWN^ISO|201602021437||RSP^K22^RSP_K21|1454416631774019|P|2.5
MSA|AA|TEST-CR-14-30
QAK|8494764101303661668890645833527|OK
QPD|Q22^Find Candidates^HL7|8494764101303661668890645833527|@PID.3.1^20287~@PID.3.4.1^DOH_fileNumber.172842~@PID.3.4.2^2.25.17843963144693579256192190624330832718.172842~@PID.3.4.3^ISO|||||^^^DHA~^^^HPRS_PATIENT_UUID
PID|||f453542f-6768-4d9a-9fd3-1310f11007d1^^^HPRS_PATIENT_UUID~9412210000081^^^DHA^NNZAF||Joy^Gladness^^^^^U||20110214|F|||7474 EXT 3B^^^^^ZA

ITI-21 request with HPRN identifier AND DOH namespace id AND NH identifier type, response includes NK1

Request

MSH|^~\&|TEST_HARNESS|TEST|CR1|MOH_CAAT|20090226131520-0600||QBP^Q22^QBP_Q21|TEST-CR-14-30|P|2.5
QPD|Q22^Find Candidates^HL7|8494764101303661668890645833527|@PID.3.1^165-676-3727~@PID.3.4.1^DOH~@PID.3.5.3^NH

Response

MSH|^~\&|HPRS|HPRS|TEST_HARNESS|TEST|201808081405||RSP^K22^RSP_K21|1533729834610149|P|2.5
MSA|AA|TEST-CR-14-30
QAK|8494764101303661668890645833527|OK
QPD|Q22^Find Candidates^HL7|8494764101303661668890645833527|@PID.3.1^165-676-3727~@PID.3.4.1^DOH~@PID.3.5.3^NH
PID|||04af6ab6-9270-11e5-9641-efed249e8181^^^HPRS_PATIENT_UUID&test-hie.health.gov.za&DNS~4004000001234^^^DHA&www.home-affairs.gov.za&DNS^NNZAF ZA ID number dispensed by dept home affairs DHA~116-222-8124^^^DOH&www.health.gov.za&DNS^NH^^20160620 ACTIVE HPRN dispensed by dept health with effective date (a patient may have multiple inactive prns and one active prn- querying by either inactive or active will be successful)~165-676-3727^^^DOH&www.health.gov.za&DNS^NH^^^20171213 INACTIVE HPRN dispensed by dept health with expiry date~0888^^^DOH&www.health.gov.za&DNS^MR^472824||filenumber for facility id 472824 as per health data dictionary
Du Toit^Stephanuse^Petrus^^^^U||19400405|F|||123 Test Loc^^Test City^^9800^ZA
NK1|1|testsurname^testfirstname^^^^^U|SIS^Sister|135 testRd^^^^^ZA|^^^^^^^^^^^0112345678

ITI-21 request with identifier - SA id number with unsupported namespace id

Request

MSH|^~\&|TEST_HARNESS|TEST|CR1|MOH_CAAT|20090226131520-0600||QBP^Q22^QBP_Q21|TEST-CR-14-30|P|2.5
QPD|Q22^Find Candidates^HL7|8494764101303661668890645833527|@PID.3.1^7804250694088~@PID.3.4.1^2DHA~@PID.3.4.3^ISO~@PID.3.5^PI
RCP|I

Response

MSH|^~\&|HPRSPIXMANAGER^2.25.17843963144693579256192190624330832714^ISO|HPRSPIXMANAGER^2.25.17843963144693579256192190624330832714^ISO|TEST_HARNESS^UNKNOWN^ISO|TEST^UNKNOWN^ISO|201602021440||RSP^K22^RSP_K21|1454416828775534|P|2.5
MSA|AE|TEST-CR-14-30
ERR||QPD^1^3^2|204|E||||unknown domain namespace id
QAK|8494764101303661668890645833527|AE
QPD|Q22^Find Candidates^HL7|8494764101303661668890645833527|@PID.3.1^7804250694088~@PID.3.4.1^2DHA~@PID.3.5^PI

ITI-21 request with identifier - SA id number with identifier type code

NOTE: If the identifierType code is not specified the response will contain all patients with any DHA identifier that matches the one in the request.

Request

MSH|^~\&|TEST_HARNESS|TEST|CR1|MOH_CAAT|20090226131520-0600||QBP^Q22^QBP_Q21|TEST-CR-14-30|P|2.5
QPD|Q22^Find Candidates^HL7|8494764101303661668890645833527|@PID.3.1^7804250694088~@PID.3.4.1^DHA~@PID.3.4.3^ISO~@PID.3.5^NNZAF
RCP|I

Response

MSH|^~\&|HPRSPIXMANAGER^2.25.17843963144693579256192190624330832714^ISO|HPRSPIXMANAGER^2.25.17843963144693579256192190624330832714^ISO|TEST_HARNESS^UNKNOWN^ISO|TEST^UNKNOWN^ISO|201602021443||RSP^K22^RSP_K21|1454416984649544|P|2.5
MSA|AA|TEST-CR-14-30
QAK|8494764101303661668890645833527|OK
QPD|Q22^Find Candidates^HL7|8494764101303661668890645833527|@PID.3.1^7804250694088~@PID.3.4.1^DHA~@PID.3.5^PI
PID|||IF82^^^DOH^MR^342415~00000179-500d-41ee-9970-131a39cf9a2e^^^HPRS_PATIENT_UUID~7804250694088^^^DHA^NNZAF||TESTSURNAME^TESTFIRSTNAME^^^^^U||19780425|F|||GOVANMBEKI LOCAL MUNICIPALITY^^^^^ZA||^^^^^^^^^^^0820314017

ITI-21 request with wildcard demographics — NOT SUPPORTED BY HPRS

Request

MSH|^~\&|TEST_HARNESS|TEST|CR1|MOH_CAAT|20090226131520-0600||QBP^Q22^QBP_Q21|TEST-CR-14-30|P|2.5
QPD|Q22^Find Candidates^HL7|8494764101303661668890645833527|@PID.5.1.1^MOFO*~@PID.5.2^Maria~@PID.8^F
RCP|I|10^RD

Response returns more than fifty candidates with continuation pointer.

ITI-21 request with continuation — SHOULD NOT BE NECESSARY

Request 1

MSH|^~\&|TEST_HARNESS|TEST|CR1|MOH_CAAT|20090226131520-0600||QBP^Q22^QBP_Q21|TEST-CR-14-30|P|2.5
QPD|Q22^Find Candidates^HL7|8494764101303661668890645833527|@PID.5.1.1^MOFO*~@PID.5.2^Maria~@PID.8^F
RCP|I|10^RD

Response 1

MSH|^~\&|HPRSPIXMANAGER^2.25.17843963144693579256192190624330832714^ISO|HPRSPIXMANAGER^2.25.17843963144693579256192190624330832714^ISO|TEST_HARNESS^UNKNOWN^ISO|TEST^UNKNOWN^ISO|201601221454||RSP^K22^RSP_K21|1453467286296055|P|2.5
MSA|AA|TEST-CR-14-30
QAK|8494764101303661668890645833527|OK
QPD|Q22^Find Candidates^HL7|8494764101303661668890645833527|@PID.5.1.1^MOFO*~@PID.5.2^Maria~@PID.8^F
PID|||2842^^^DOH fileNumber~013a10be-9fdd-11e5-9ad1-1ffb131933a4^^^HPRS PATIENT UUID||MOFOKENG^MARIA^^^^^U||19750107|F|||370 SLOVOPARK^^^^9870^ZA^^^WITSIESHOEK
PID (9 more)
DSC|10|I

(continuation pointer of 10) – to obtain the following ten records the next request should look as follows:

Request 2

MSH|^~\&|TEST_HARNESS|TEST|CR1|MOH_CAAT|20090226131520-0600||QBP^Q22^QBP_Q21|TEST-CR-14-30|P|2.5
QPD|Q22^Find Candidates^HL7|8494764101303661668890645833527|@PID.5.1.1^MOFO*~@PID.5.2^Maria~@PID.8^F
RCP|I|10^RD
DSC|10|I

(start with an offset of 10 and return the following 10 records)

ITI-21 request with fuzzy search — NOT SUPPORTED BY HPRS

Request

MSH|^&~\|CLINREG|WESTCLIN|HOSPMPI|HOSP|199912121135-0600||QBP^Q22^QBP_Q21|1|D|2.5
QPD|Q22^Find Candidates^HL7nnn|111069|@PID.5.1^SMITH~@PID.5.2^JOHN~@PID.8^M|80|MATCHWARE|1.2||^^^METRO HOSPITAL~^^^SOUTH LAB|
RCP||I|20^RD

Response

MSH|^&~\|HOSPMPI|HOSP|CLINREG|WESTCLIN|199912121135-0600||RSP^K22^RSP_K21|1|D|2.5
MSA|AA|8699|
QAK|111069|OK|Q22^Find Candidates^HL7nnnn|3|
QPD|Q22^Find Candidates^HL7nnn|111069|@PID.5.1^SMITH~@PID.5.2^JOHN~@PID.8^M|80|MATCHWARE|1.2||^^^METRO HOSPITAL~^^^SOUTH LAB|
PID|||66785^^^METRO HOSPITAL~66532^^^SOUTH LAB||Smith^John||19630423|M||C|N2378 South Street^^Madison^WI^53711|
QRI|95||MATCHWARE 1.2|
PID|||87443^^^METRO HOSPITAL~651189^^^SOUTH LAB||Smith^Jon||19470606|M||C|124 Second Street^^Madison^WI^53711|
QRI|90||MATCHWARE 1.2|
PID|||43266^^^METRO HOSPITAL~81209^^^SOUTH LAB||Smithy^John||19901210|M||C|W11234 Bay Drive^^Lodi^WI^53555|
QRI|85||MATCHWARE 1.2|

ITI-21 request with DOH namespace

This queries for a patient associated with facilityid (137321) and filenumber (MR=medical record) (20287).

Request

MSH|^~\&|TEST_HARNESS|TEST|CR1|MOH_CAAT|20090226131520-0600||QBP^Q22^QBP_Q21|TEST-CR-14-30|P|2.5
QPD|Q22^Find Candidates^HL7|8494764101303661668890645833527|@PID.3.1^20287~@PID.3.4.1^DOH~@PID.3.5.5^MR~@PID.3.6.1^137321
RCP|I

Response

MSH|^~\&|HPRSPIXMANAGER^2.25.17843963144693579256192190624330832714^ISO|HPRSPIXMANAGER^2.25.17843963144693579256192190624330832714^ISO|TEST_HARNESS^UNKNOWN^ISO|TEST^UNKNOWN^ISO|201602021429||RSP^K22^RSP_K21|1454416180860118|P|2.5
MSA|AA|TEST-CR-14-30
QAK|8494764101303661668890645833527|OK
QPD|Q22^Find|@PID.3.1^20287~@PID.3.4.1^DOH~@PID.3.5.5^MR~@PID.3.6.1^137321
PID|||20287^^^DOH&www.health.gov.za&DNS^MR^20287~f453542f-6768-4d9a-9fd3-1310f11007d1^^^HPRS_PATIENT_UUID~1102140000081^^^DHA^NNZAF||testsurname^testfirstname^^^^^U||20110214|F|||7474 EXT 3B^^^^^ZA

Supported Identifiers

Field 3 of the PID segment is the Patient Identifier List. It is used within most messages either to query a patient with a certain identifier, or when returning information regarding a patient including identifiers for that patient. Within HPRS the following types of identifiers are supported for use within the Patient Identifier List:

NOTE: in order to distinguish between unverified NNZAF and verified NNZAF (via DHA), PID.32 (Table 0445) will be used. In the case of an UNVERIFIED NNZAF the value will be UNNZAF (unknown South African DHA ID number).

Identifier Type	Assigning Authority (Table0363)	Identifier Type Code (Table0203)	Assigning Jurisdiction	Assigning Facility	ITI-21 Example	ITI-8 Example	Notes
South African Id Number	DHA	NNZAF			@PID.3.1^7804250694088~@PID.3.4.1^DHA~@PID.3.5.3^NNZAF	7804250694088^^^DHA^NNZAF	Assigning Authority namespaceid and identifier type code associated with the identifier must be specified
Asylumseeker - Section 22 permit	DHA	VP			@PID.3.1^37691aafr44~@PID.3.4.1^DHA~@PID.3.5.3^VP	37691aafr44^^^DHA^VP	Assigning Authority namespaceid and identifier type code associated with the identifier must be specified
South African passport number	DHA	PPN			@PID.3.1^pp11111154632~@PID.3.4.1^DHA~@PID.3.5.3^PPN	pp11111154632^^^DHA^PPN	Assigning Authority namespaceid and identifier type code associated with the identifier must be specified
Legal refugee - Section 24 permit	DHA	TPR			@PID.3.1^rn11111154632~@PID.3.4.1^DHA~@PID.3.5.3^TPR	rn11111154632^^^DHA^TPR	Assigning Authority namespaceid and identifier type code associated with the identifier must be specified
Foreign passport number	FOREIGN_GOVT	PPN	ZWE		@PID.3.1^pp11111154632~@PID.3.4.1^FOREIGN_GOVT~@PID.3.5.3^PPN~@PID.3.9.1^ZWE	pp11111154632^^FOREIGN_GOVT^^^ZWE^PPN	Assigning Authority namespaceid and identifier type code associated with the identifier must be specified
Facility File Number	DOH	MR		<6digitfacilityid>	@PID.3.1^2876~@PID.3.4.1^DOH~@PID.3.5.3^MR~@PID.3.6.1^137321	2876^^^DOH^MR^137321	Assigning Authority namespaceid and identifier type code associated with the identifier must be specified
HPRN number	DOH	NH			@PID.3.1^11111154632~@PID.3.4.1^DOH~@PID.3.5.3^NH	11111154632^^^DOH^NH	Assigning Authority namespaceid and identifier type code associated with the identifier must be specified

PID segment Definition

HL7 v2.3.1 — PID fields

SEQ	LEN	DT	OPT	RP/#	TBL#	Element Name	Comment
1	4	SI	O			Set ID - PID	Number to identify the transaction - first one is 1, then 2, etc.
2	20	CX	B			Patient ID	Used for backward compatibility only; should rather use PID-3.
3	20	CX	R	Y		Patient Identifier List	List of identifiers used to uniquely identify patient
4	20	CX	B	Y		Alternate Patient ID - PID	Used for backward compatibility only; should rather use PID-3.
5	48	XPN	R	Y		Patient Name	Legal or primary name of the patient. All other names should be in PID-9. Name type should be 'L - Legal'. Repetition allowed for representing same name in different character sets.
6	48	XPN	O	Y		Mother's Maiden Name	Family name under which the mother was born; distinguishes patients with the same last name.
7	26	TS	O			Date/Time of Birth	The patient's date and time of birth
8	1	IS	O		0001	Sex	The patient's sex
9	48	XPN	O	Y		Patient Alias	Patient's alias/other names
10	80	CE	O	Y	0005	Race	The patient's race
11	106	XAD	O	Y		Patient Address	Mailing address of the patient
12	4	IS	B		0289	County Code	For backward compatibility, rather use PID-11
13	40	TN	O	Y		Phone number - Home	Patient's personal phone numbers
14	40	TN	O	Y		Phone number - Business	Patient's business telephone numbers
15	60	CE	O		0296	Primary Language	The patient's primary language
16	80	CE	O		0002	Marital Status	The patient's marital (civil) status
17	80	CE	O		0006	Religion	The patient's religion
18	20	CX	O			Patient Account Number	Account number to which all charges, payments, etc. are recorded
19	16	ST	B			SSN Number - Patient	For backward compatibility; use PID-3
20	25	DLN	O			Driver's Licence Number - Patient	Default second component is state in which license is registered
21	20	CX	O	Y		Mother's Identifier	Used as a link field for newborns
22	80	CE	O	Y	0189	Ethnic Group	Defines the patient's ancestry
23	60	ST	O			Birth Place	The location of the patient's birth
24	1	ID	O		0136	Multiple Birth Indicator	Indicates whether the patient was part of a multiple birth
25	2	NM	O			Birth Order	If part of multiple birth, indicates birth order
26	80	CE	O	Y	0171	Citizenship	Patient's country citizenship
27	60	CE	O		0172	Veterans Military Status	Military status assigned to a veteran
28	80	CE	O		0212	Nationality	Nation or national grouping to which the person belongs
29	26	TS	O			Patient Death Date and Time	The date and time at which death occurred
30	1	ID	O		0136	Patient Death Indicator	Indicates whether the patient is deceased

HL7 v2.5 — PID fields (additional/changed vs v2.3.1)

Fields 1–30 are broadly similar to v2.3.1 (with field lengths extended to 250 for many fields, and PID-9 becoming backward-compatible-only). Additional fields in v2.5:

SEQ	LEN	DT	OPT	RP/#	TBL#	Element Name	Comment
31	1	ID	O		0136	Patient Unknown Indicator	Indicates whether or not the patient's/person's identity is known
32	20	IS	O	Y	0445	Identity Reliability Code	Coded value used to communicate the reliability of patient/person identifying data
33	26	TS	O			Last Update Date/Time	Last update date/time for the patient's identifying and demographic data
34	241	HD	O			Last Update Facility	Identifies the facility of the last update (DHIS DD codes recommended)
35	250	CE	C		0446	Species Code	Species of living organism; if not specified, 'human' is assumed
36	250	CE	C		0447	Breed Code	Breed of animal (animals only)
37	80	ST	O			Strain	Specific strain of animal
38	250	CE	O		0429	Production Class Code	Primary use for which the living subject was bred or grown
39	250	CWE	O	Y	0171	Tribal Citizenship	Information about the tribal membership of the patient

Table0203

See PDQm-Table0203 for the full HL7 Table 0203 (Identifier type) values for both v2.3.1 and v2.5 — the tables are identical.

Table0363

HL7 Table 0363 (Assigning authority)

Basic information: Table 0363, Type: User, Name: Assigning authority

Detail: This table is used to encode the namespace of an assigning authority used within a Patient Identifier List. As a user-defined table, values are identical across all HL7 versions (values shown below use HL7 v2.5).

Value	Description
DHA	Department of Home Affairs - this namespaceid covers all identifiers issued by the DHA, identifiers should be distinguished by identifiertypecode.
HPRS_PATIENT_UUID	Internal patient Identifier for HPRS system
DOH	Department of Health - this namespaceid covers all identifiers issued by the DOH, identifiers should be distinguished by identifiertypecode. (MR for filenumber (must also submit a facilityid), NH for PRN)
FOREIGN_GOVT	Any foreign government; identifiers should be distinguished by identifiertypecode and country should be distinguished by assigning jurisdiction

Table 0445

HL7 Table 0445 (Identity Reliability Code)

Basic information: Table 0445, Type: User, Name: Identity Reliability Code

Detail: This table is used to encode the form of identity supplied that is unreliable.

Value	Description
UNNZAF	Department of Home Affairs – South African Identification Number is UNVERIFIED

Article Sources and Contributors

• ITI-21 — Contributors: Kdutoit
• ITI-21 Request Message Header — Contributors: Kdutoit, RAlberts
• ITI-21 Request Query Parameter Definition — Contributors: Kdutoit, RAlberts
• ITI-21 Request Response Control Parameter — Contributors: Kdutoit, RAlberts
• ITI-21 Request Continuation Pointer — Contributors: Kdutoit, RAlberts
• ITI-21 Response Message Header — Contributors: Kdutoit, RAlberts
• ITI-21 Response Message Acknowledgement — Contributors: Kdutoit
• ITI-21 Response Error — Contributors: Kdutoit
• ITI-21 Response Query Acknowledgement — Contributors: Kdutoit
• ITI-21 Response Query Parameter Definition — Contributors: Kdutoit, RAlberts
• ITI-21 Response Patient Identification — Contributors: Kdutoit, RAlberts
• HL7 NK1 — Contributors: Kdutoit
• ITI-21 Response Continuation Pointer — Contributors: Kdutoit
• V2.5 HL7 Communication standard — Contributors: Kdutoit, Kvdwalt, RAlberts
• ITI-21 Examples — Contributors: Kdutoit, RAlberts
• Supported Identifiers — Contributors: Kdutoit
• PID segment — Contributors: Tfogwill
• Table0203 — Contributors: Tfogwill
• Table0363 — Contributors: Kdutoit

(Source references originally point to http://health-docs.dhcp.meraka.csir.co.za/mediawiki/index.php?oldid=... internal wiki article revisions.)

Table0002

See PDQm-Table0002 for the full HL7 Table 0002 (Marital Status) values.

MPI name search implementation

NOT SUPPORTED BY HPRS

1. An input search string without accents will match names with and without accents.
2. An input search string with an accent will match names with and without accents.
3. An input search string with an apostrophe will match names with and without an apostrophe.
4. An input search string with a hyphen will only match a name with a hyphen.
5. An input search string without a hyphen will not match a name with a hyphen.
6. An input firstname (givenname) @PID.5.2 with a space in it will be split into 2 strings, and both the first string and the full string will be used to match to firstname.
7. When searching on an idnumber AND a name, the patient with names within an edit distance of one will be returned.

Important Links: HL7

• HL7 v2 general information: https://hl7-definition.caristix.com/v2/
• HL7 v2 ER7 segment definitions in detail: https://hl7-definition.caristix.com/v2/HL7v2.5.1/Segments
• HL7 v2 tables: https://hl7-definition.caristix.com/v2/HL7v2.5.1/Tables
• HL7 Online parsers:
  • https://hl7messageparser.azurewebsites.net/Parse/ParseView
  • https://www.hl7inspector.com/
• HL7 libraries:
  • nodejs: https://www.npmjs.com/package/simple-hl7
  • python: https://pypi.org/project/hl7/
  • c#: https://www.nuget.org/packages/nhapi
  • java: https://hapifhir.github.io/hapi-hl7v2/

HPRS-ITI-21

Contents

• ITI-21
• ITI-21 Summary
  • ITI-21 Patient Demographics Query
  • RESPONSE FORMAT
• 2. ITI-21 Request
  • 2a. ITI-21 Request Message Header
  • 2b. ITI-21 Request Query Parameter Definition
  • 2c. ITI-21 Request Response Control Parameter
  • 2d. ITI-21 Request Continuation Pointer
• 3. ITI-21 Response RSP_K22
  • 3a. ITI-21 Response Message Header
  • 3b. ITI-21 Response Message Acknowledgement
  • 3c. ITI-21 Response Error
  • 3d. ITI-21 Response Query Acknowledgement
  • 3e. ITI-21 Response Query Parameter Definition
  • 3f. ITI-21 Response Patient Identification
  • 3g. ITI-21 Response Next of Kin
  • 3h. ITI-21 Response Continuation Pointer
• PDQexamples

HPRS Implementation of ITI-21 — PDQ (Patient Demographics Query)

Author: Kirsten du Toit — Version: 1.0 — HPRS Version: 1.10.0 — Date: 19/03/2019

ITI-21 Summary

ITI-21 Patient Demographics Query

REQUEST FORMAT

The format of the query message is the HL7 QBP^Q22 message — IHE IT Infrastructure Technical Framework, Volume 2a (p. 149). If the incoming message is a QBP message of type Q22, the solution retrieves a list of demographic information from the EMPI for patients that match the search data specified in the incoming message. The query results are returned in an RSP (response) message.

Trigger Events: For selecting a patient based on demographic information about patients whose information matches a minimal set of known data: Q22 – Find Candidates.

[]=optional, {}=multiple allowed, otherwise required.

• MSH (2a. ITI-21 Request Message Header)
• QPD (2b. ITI-21 Request Query Parameter Definition)
• RCP (2c. ITI-21 Request Response Control Parameter)
• [ DSC[ ] ] (2d. ITI-21 Request Continuation Pointer)

RESPONSE FORMAT

For unsuccessful queries, an AE RSP, AE ACK, or AR ACK message is returned, depending on the reason for the failure. Additional information about the failure is contained in the ERR segment of the response.

Required Format:

• MSH (3a. ITI-21 Response Message Header)
• MSA (3b. ITI-21 Response Message Acknowledgement)
• [[ {ERR} ]] (3c. ITI-21 Response Error)
• QAK (3d. ITI-21 Response Query Acknowledgement)
• QPD (3e. ITI-21 Response Query Parameter Definition)
• [ { PID[ (3f. ITI-21 Response Patient Identification) [ PD1 ] [{NK1 (Next of Kin)}] [ QRI Query Response Instance] } ]
• [ DSC[ ] ] (3h. ITI-21 Response Continuation Pointer)

2. ITI-21 Request

2a. ITI-21 Request Message Header

ITI-21 REQUEST MSH SEGMENT

Example:

MSH|^~\&|RXSOLUTIONS|171234|HPRSPIXPDQ|CENTRAL|20090224104204-0600|2a777bf6-1ba1-11ec-a451-6f38e66abc76$9402041167082|QBP^Q22^QBP_Q21|9241351356666182528|P|2.5

SEQ	LEN	DT	OPT	RP/#	TBL#	Element Name	Value per Example	Notes
1	1	ST	R			Field Separator	|	Character used as separator for the rest of the message
2	4	ST	R			Encoding Characters	^~\&	Message delimiters: component separator, repetition separator, escape character, subcomponent separator
3	180	HD	O			Sending Application	RXSOLUTIONS	Uniquely identifies the sending application - site defined
4	180	HD	O			Sending Facility	171234	Address of one of several occurrences of the same application within the sending system; in the example this is the 6 digit facility ID as per the DOH - user defined
5	180	HD	O			Receiving Application	HPRSPIXPDQ	Site defined
6	180	HD	O			Receiving Facility	CENTRAL	Site defined
7	26	TS	O			Date/Time Of Message	20090224104204-0600	Date/time sending system created the message, i.e. now()
8	40	ST	O			Security	2a777bf6-1ba1-11ec-a451-6f38e66abc76$9402041167082$Joe$Test$joetest@csir.co.za$0110001111$146.64.1.1$maternity — format: accountid$Idnumber$firstname$surname$email$phonenumber$ipaddress$wardname	Contains account information for the original requester. User details separated by $. If information is unavailable it is acceptable to leave fields blank. The system unique accountid of the original requester is required and MUST be sent.
9	7	CM	R		0076,0003	Message Type	QBP^Q22^QBP_Q21	Predefined for ITI-21
10	20	ST	R			Message Control ID	9241351356666182528	Unique identifier for this message
11	3	PT	R		0103	Processing ID	P	D=Debugging, P=Production, T=Training
12	8	ID	R		0104	Version ID	2.5	HL7 version of this message

2b. ITI-21 Request Query Parameter Definition

ITI-21 REQUEST QPD SEGMENT

Example:

QPD|IHE PDQ Query|8494764101303661668890645833527|@PID.3.1^165-652-1397~@PID.3.4.1^DOH~@PID.3.5^NH

SEQ	LEN	DT	OPT	RP/#	TBL#	Element Name	Value per Example	Notes
1	250	CE	R		0471	Message Query Name	IHE PDQ Query	Predefined for ITI-21
2	32	ST	R			Query Tag	8494764101303661668890645833527	Uniquely identifies query
3	250	QIP	R			Demographics Fields	Query by idnumber: @PID.3.1^7804250694088~@PID.3.4.1^DHA~@PID.3.5.3^NNZAF; Query by demographics: @PID.5.1.1^MOFO*~@PID.5.2^Maria~@PID.8^F~@PID.13.1^0736705638; Query by PRN: @PID.3.1^165-652-1397~@PID.3.4.1^DOH~@PID.3.5^NH	The first component of each parameter contains the name of an HL7 element in the form @<seg>.<field position>.<component position>.<subcomponent position>
4	250	CX	O		0363	What Domains Returned	^^^DHA~^^^HPRS_PATIENT_UUID	Restricts the set of domains for which identifiers are returned in PID-3: only component 4 (Assigning Authority) shall be valued. If empty, all identifiers for all domains supported are returned.

Querying with Demographics — NOT SUPPORTED BY HPRS

Example query by demographics:

QPD|IHE PDQ Query|8494764101303661668890645833527|@PID.5.1.1^MOFO*~@PID.5.2^Maria~@PID.8^F~@PID.13.1^0736705638

Query Element	PID Mapping	Value per Example	Notes
@PID.5.1.1	patientName.familyName.surname	MOFO*	Wildcards are supported
@PID.5.2	PatientName.givenName	Maria	Wildcards are supported
@PID.7.1	Date/time of Birth	19780425	yyyymmdd (degree of precision not yet supported); putting date of birth as 197804 would allow search of all birth dates within April 1978
@PID.8	Administrative sex	F	F:female, M:male, U:unknown, A:ambiguous
@PID.11	Patient Address		Subcomponents specified in PID segment
@PID.13.1	Phone Number	0736705638	South African phone number
@PID.13.12	Unformatted Phone Number	+27(73 670 5638)	Unformatted South African phone number

Querying with Identifiers

Please refer to Supported Identifiers for information on how to construct the query fields for identifiers such as South African Passport Number, South African Id Number, Department of Health facility folder number etc.

Example query by South African IDNumber:

QPD|IHE PDQ Query|8494764101303661668890645833527|@PID.3.1^7804250694088~@PID.3.4.1^DHA~@PID.3.5^NNZAF

Example query by Patient Record Number:

QPD|IHE PDQ Query|8494764101303661668890645833527|@PID.3.1^165-652-1397~@PID.3.4.1^DOH~@PID.3.5^NH

Query Element	PID Mapping	Value per Example	Notes
@PID.3.1	PatientIdentifierList.idNumber	7804250694088 / 165-652-1397	South African ID number / HPRN number
@PID.3.4.1	PatientIdentifierList.assigningAuthority.namespaceid	DHA / DOH	The namespaceid for the domain that assigned the identifier, DHA=Dept of Home Affairs, DOH=Dept of Health
@PID.3.5	PatientIdentifierList.identifierTypecode	NNZAF / NH	Specifies the type of identifier being used in the query – restricts identifiers found within the assigning authority domain requested to the type requested (Table0203). NNZAF = South African National Identifier, NH = National Health identifier

2c. ITI-21 Request Response Control Parameter

ITI-21 REQUEST RCP SEGMENT

Example:

RCP|I|10^RD

SEQ	LEN	DT	OPT	RP/#	TBL#	Element Name	Value per Example	Notes
1	1	ID	O		0091	Query Priority	I	Signifies an immediate response requested - predefined for ITI-21
2	10	CQ	O		0126	Quantity Limited Request	10^RD	If the query could result in hundreds/thousands of matches, response may be limited using the HL7 continuation protocol

2d. ITI-21 Request Continuation Pointer

ITI-21 REQUEST DSC SEGMENT

The DSC segment should be omitted on the initial query request. Its purpose is to request additional increments of data from the Patient Demographic Supplier Actor.

Example:

DSC|10|I

SEQ	LEN	DT	OPT	RP/#	Element Name	Value per Example	Notes
1	180	ST	O		Continuation Pointer	10	To request additional increments, DSC-1 shall echo the value from RSP^K22 DSC-1
2	1	ID	O		Continuation Style	I	Signifies this is part of an interactive continuation message - predefined for ITI-21

3. ITI-21 Response RSP_K22

3a. ITI-21 Response Message Header

ITI-21 RESPONSE MSH SEGMENT

Example:

MSH|^~\&|HPRSPIXPDQ|171234|RXSOLUTIONS|CENTRAL|20090224104204-0600||RSP^K22^RSP_K21|9241351356666182529|P|2.5

SEQ	LEN	DT	OPT	RP/#	TBL#	Element Name	Value per Example	Notes
1	1	ST	R			Field Separator	|	Character used as separator for the rest of the message
2	4	ST	R			Encoding Characters	^~\&	Message delimiters
3	180	HD	O			Sending Application	HPRSPIXPDQ	Uniquely identifies sending application - site defined
4	180	HD	O			Sending Facility	CENTRAL	Address of an occurrence of the same application within the sending system
5	180	HD	O			Receiving Application	RXSOLUTIONS	Site defined
6	180	HD	O			Receiving Facility	171234	Site defined; in the example this is the 6 digit DOH facility ID as per the request
7	26	TS	O			Date/Time Of Message	20090224104204-0600	Date/time sending system created the message
8	40	ST	O			Security
9	7	CM	R		0076,0003	Message Type	RSP^K22^RSP_K21	Predefined for ITI-21 Response
10	20	ST	R			Message Control ID	9241351356666182529	Unique identifier for this message
11	3	PT	R		0103	Processing ID	P	D=Debugging, P=Production, T=Training
12	8	ID	R		0104	Version ID	2.5	HL7 version of this message

3b. ITI-21 Response Message Acknowledgement

ITI-21 RESPONSE MSA SEGMENT

Example:

MSA|AA|TEST-CR-14-30

MSA-1: Acknowledgement code (ID); MSA-2: Message Control ID (ST); MSA-3: Text Message (ST) optional; MSA-4: Expected Sequence Number (NM) optional; MSA-5: Delayed Acknowledgement Type (ID) optional; MSA-6: Error Condition (CE) optional.

SEQ	LEN	DT	OPT	RP/#	TBL#	Element Name	Value per Example	Notes
1	1	ID	R			Acknowledgement code	AA	Indicates whether or not the message was successfully received and processed ('AA' for a positive ACK; 'AE' or 'AR' for a negative ACK — application accept/error/reject)
2	4	ST	R			Message Control ID	TEST-CR-14-30	The control Id of the request

3c. ITI-21 Response Error

Error Segment (ERR) Specifications

The ERR segment is used to add error comments to acknowledgment messages. It is only populated for AR or AE type acknowledgments. HPRS currently only returns an AE acknowledgement.

ERR||QPD^1^3^2|204|E|||| query is too vague, query requires either phonenumber, dateofbirth, both firstname and surname, both id and assigningauthorityid parameters
ERR||QPD^1^3^2|204|E|||| wildcard query is too vague, firstname or surname first character may not be a wildcard
ERR||QPD^1^3^2|204|E|||| wildcard query is too vague, surname length should be at least 4 chars plus wildcard
ERR||QPD^1^3^2|204|E|||| wildcard query is too vague, firstname length should be at least 4 chars plus wildcard
ERR||QPD^1^3^2|204|E|||| dateofbirth - invalid date or format - must be yyyymmdd or yyyymm or yyyy
ERR||QPD^1^3^2|204|E|||| invalid query
ERR||QPD^1^3^1|101|E|||| pdq query requires an id number
ERR||QPD^1^3^1|101|E|||| pdq query requires a domain
ERR||QPD^1^3^1^4|204|E|||| unknown domain
ERR||QPD^1^3^1^4|204|E|||| unknown domain namespace id
ERR||QPD^1^3^1^4|204|E|||| unknown domain universal id
ERR||QPD^1^3^2|204|E|||| invalid continuation pointer or quantity limit
ERR||QPD^1^4^1|204|E|||| unknown domain in whatdomainsreturned
ERR||QPD^1^3^2|204|E||||this id is not known
ERR||QPD^1^3^2|204|E||||unknown domain namespace id

SEQ	LEN	DT	OPT	RP/#	TBL#	Element Name	Value per Example	Notes
1	493	ELD	B			Error Code and Location		Supported for backward compatibility only
2	18	ERL	R			Error Location	QPD^1^3^2	Identifies the location in a message related to the identified error, warning or message. Components: <Segment ID>^<Segment Sequence>^<Field Position>^<Field Repetition>^<Component Number>
3	705	CWE	R			Error Code	204	204=unknown key identifier, 101=required field missing
4	2	ID	R			Severity	E	I=information, E=error, W=warning
8	250	TX	O			User Message	unknown domain namespace id

3d. ITI-21 Response Query Acknowledgement

Query Acknowledgement Segment (QAK) Specifications

QAK|111069|OK|Q22^Find Candidates^HL7nnnn|3|

SEQ	LEN	DT	OPT	RP/#	TBL#	Element Name	Value per Example	Notes
1	32	ST	R			Query Tag	111069	Contains value sent in QPD-2 (query tag) by initiating system; used to match response messages to originating query. Responding system echoes it back as the first field of QAK.
2		ID	R		0208	Query Response Status	OK	Allows responding system to return a precise response status; useful when no data found but no error either
3		CE	R			Message Query Name	Q22^Find Candidates^HL7nnnn	Mirrors QPD-1 (Message Query Name) from the query message being responded to
4		NM	O			Hit count	3 (not supported)	Total number of matches
5		NM	O			This Payload	Not supported	Number sent in this response
6		NM	O			Hits Remaining	Not supported	Number left after this response

3e. ITI-21 Response Query Parameter Definition

Response Query Parameter Definition Segment (QPD)

QPD|Q22^Find Candidates^HL7|8494764101303661668890645833527|@PID.3.1^7804250000088@PID.3.4.1^2DHA@PID.3.5.3^PI

SEQ	LEN	DT	OPT	RP/#	TBL#	Element Name	Value per Example	Notes
1	32	CE	R			Message Query Name	Q22^Find Candidates^HL7	Name of the query, assigned by function-specific chapters of this specification; one to one with the conformance statement for this query name
2		ST	R			Query Tag	8494764101303661668890645833527	Must be valued by initiating system to identify the query; used to match response messages. Differs from MSA-2 in that its value remains constant for each message associated with the query.
3		Varies	R			User Parameters (successive fields)	@PID.3.1^7804250000088~@PID.3.4.1^2DHA~@PID.3.5.3^PI	Successive parameter fields hold the values the client passes to the server, as a sequence of HL7 fields. Understood positionally per the Conformance Statement. See 2b. ITI-21 Request Query Parameter Definition

3f. ITI-21 Response Patient Identification

Response Patient Identification Segment Definition

The Patient Demographics Supplier Actor shall return one PID segment group (PID segment plus any associated segments) for each matching patient record found. The Supplier shall return the attributes within the PID segment as specified below, plus all other attributes for which it can supply values. Inability to supply an identifier in a particular domain (specified in QPD-8) is not an error, provided the domain is recognized.

Example:

PID|||IF82^^^DOH^MR^342415~00000179-500d-41ee-9970-131a39cf9a2e^^^HPRS_PATIENT_UUID~7804250000088^^^DHA^NNZAF~140-741-1626^^^DOH&www.health.gov.za&DNS^NH^^^20180704 (INACTIVE PRN with expiry date)~143-153-8008^^^DOH&www.health.gov.za&DNS^NH^^20180704 (ACTIVE PRN with effective date)|TESTSURNAME^TESTFIRSTNAME^^^^^U||19780425|F|||GOVAN MBEKI LOCAL MUNICIPALITY^^^^^ZA|^^^^^^^^^^^0820314017

SEQ	LEN	DT	OPT	RP/#	Element Name	Value per Example	Notes
3	250	CX	R		Patient Identifier List	IF82^^DOH^MR~7804250000088^^^DHA^NNZAF~140-741-1626^^^DOH&www.health.gov.za&DNS^NH^^^20180704~143-153-8008^^^DOH&www.health.gov.za&DNS^NH^^20180704	A patient may have multiple NH identifiers. PRN numbers can be active, inactive or neither; all are valid for querying. An ACTIVE PRN has an effective date, an INACTIVE PRN has an expiration date.
5	250	XPN	R		Patient Name	TESTSURNAME^TESTFIRSTNAME^^^^^U
7	26	TS	R2		Date/Time of Birth	19780425	yyyymmdd
8	1	IS	R2		Administrative Sex	F
11	250	XAD	R2		Patient Address	GOVAN MBEKI LOCAL MUNICIPALITY^^^^^ZA
15	60	CE	O		Primary Language	See ISO 639-3 codes (AFR, ENG, NDE, SASL, SEP, SES, SWA, TSO, TSW, VEN, XHO, ZUL, etc.)	https://iso639-3.sil.org/code_tables/639/data
16	1	IS	O		Marital Status	D=Divorced, L=Separated, M=Married, S=Single, T=Registered Domestic Partnership, W=Widowed
32	20	IS	R		Identity Reliability Code	UNNZAF	If idnumbers returned have not been verified by the DHA, PID.32 will be populated with UNNZAF – unverified nnzaf identifier

CX subcomponent structure (Patient Identifier List component parts):

SEQ	LENGTH	DT	OPT	TBL#
CX.1	15	ST	R
CX.2	1	ST	O
CX.3	3/227	ID/HD	O	0061 / 0363
CX.4
CX.5	5	ID	O	0203
CX.6	227	HD	O
CX.7	8	DT	O
CX.8	8	DT	O
CX.9	705	CWE	O
CX.10	705	CWE	O

3g. ITI-21 Response Next of Kin

Response Next Of Kin Segment Definition

The NK1 segment contains information about the patient's other related parties. Utilizing NK1-1 (Set ID), multiple NK1 segments can be sent per patient.

Example:

NK1|1|testsurname^testfirstname^^^^^U|SIS^Sister|135 testRd^^^^^ZA|^^^^^^^^^^^0112345678

SEQ	LEN	DT	OPT	RP/#	TBL#	Element Name
NK1.1	4	SI	R			Set ID - NK1
NK1.2	250	XPN	O	*		NK Name
NK1.3	250	CE	O	1	0063	Relationship
NK1.4	250	XAD	O	*		Address
NK1.5	250	XTN	O	*		Phone Number
NK1.6	250	XTN	O	*		Business Phone Number
NK1.7	250	CE	O	1	0131	Contact Role
NK1.8	8	DT	O	1		Start Date
NK1.9	8	DT	O	1		End Date
NK1.10	60	ST	O	1		Next of Kin / Associated Parties Job Title
NK1.11	20	JCC	O	1		Next of Kin / Associated Parties Job Code/Class
NK1.12	250	CX	O	1		Next of Kin / Associated Parties Employee Number
NK1.13	250	XON	O	*		Organization Name - NK1
NK1.14	250	CE	O	1	0002	Marital Status
NK1.15	1	IS	O	1	0001	Administrative Sex
NK1.16	26	TS	O	1		Date/Time of Birth
NK1.17	2	IS	O	*	0223	Living Dependency
NK1.18	2	IS	O	*	0009	Ambulatory Status
NK1.19	250	CE	O	*	0171	Citizenship
NK1.20	250	CE	O	1	0296	Primary Language
NK1.21	2	IS	O	1	0220	Living Arrangement
NK1.22	250	CE	O	1	0215	Publicity Code
NK1.23	1	ID	O	1	0136	Protection Indicator
NK1.24	2	IS	O	1	0231	Student Indicator
NK1.25	250	CE	O	1	0006	Religion
NK1.26	250	XPN	O	*		Mother's Maiden Name
NK1.27	250	CE	O	1	0212	Nationality
NK1.28	250	CE	O	*	0189	Ethnic Group
NK1.29	250	CE	O	*	0222	Contact Reason
NK1.30	250	XPN	O	*		Contact Person's Name
NK1.31	250	XTN	O	*		Contact Person's Telephone Number
NK1.32	250	XAD	O	*		Contact Person's Address
NK1.33	250	CX	O	*		Next of Kin/Associated Party's Identifiers
NK1.34	2	IS	O	1	0311	Job Status
NK1.35	250	CE	O	*	0005	Race
NK1.36	2	IS	O	1	0295	Handicap
NK1.37	16	ST	O	1		Contact Person Social Security Number
NK1.38	250	ST	O	1		Next of Kin Birth Place
NK1.39	2	IS	O	1	0099	VIP Indicator

3h. ITI-21 Response Continuation Pointer

ITI-21 RESPONSE DSC SEGMENT

If the number of records is specified in RCP-2 (Quantity Limited Request), the Patient Demographics Supplier Actor shall return an incremental response of that number of records when the number of matching records found exceeds RCP-2. As long as the Supplier has records left to return, it shall return a DSC Segment containing a unique alphanumeric value (Continuation Pointer) that the Consumer may return in the DSC of the following QBP^Q22 message to request the next increment. The Supplier shall return increments as many times as requested (while increments remain), stopping when there are no more to return.

Example:

DSC|10|I

SEQ	LEN	DT	OPT	RP/#	Element Name	Value per Example	Notes
1	180	ST	O		Continuation Pointer	10	To request additional increments, DSC-1 of the following request shall echo the value from RSP^K22 DSC-1
2	1	ID	O		Continuation Style	I	Signifies part of an interactive continuation message - predefined for ITI-21

PDQexamples

ITI-21 PDQ MESSAGE EXAMPLES

Author: Kirsten du Toit — Version: 1.0 — Date: 19/03/2019

REQUEST WITH PRN WITHOUT HYPHENS

MSH|^~\&|TEST_HARNESS|TEST|CR1|MOH_CAAT|20090226131520-0600||QBP^Q22^QBP_Q21|TEST-CR-14-30|P|2.5
QPD|Q22^Find Candidates^HL7|8494764101303661668890645833527|@PID.3.1^1571472263~@PID.3.4.1^DOH
RCP|I

MSH|^~\&|HPRS|HPRS|TEST_HARNESS|TEST|201809261238||RSP^K22^RSP_K21|1539592665343843|P|2.5
MSA|AA|TEST-CR-14-30
QAK|8494764101303661668890645833527|OK
QPD|Q22^Find Candidates^HL7|8494764101303661668890645833527|@PID.3.1^1571472263~@PID.3.4.1^DOH
PID|||e5ced406-e512-11e5-abc1-63660d354159^^^HPRS_PATIENT_UUID&test-hie.health.gov.za&DNS~6610280162082^^^DHA&www.home-affairs.gov.za&DNS^NNZAF~157-147-2263^^^DOH&www.health.gov.za&DNS^NH20160308~157-147-2263^^^DOH&www.health.gov.za&DNS^MR^371924~157-147-2263^^^DOH&www.health.gov.za&DNS^MR^942124~157-147-2263^^^DOH&www.health.gov.za&DNS^MR^735042~157-147-2263^^^DOH&www.health.gov.za&DNS^MR^833442~157-147-2263^^^DOH&www.health.gov.za&DNS^MR^625251~157-147-2263^^^DOH&www.health.gov.za&DNS^MR^687651~157-147-2263^^^DOH&www.health.gov.za&DNS^MR^475542||Marais^Elliot^^^^^U||19661028|F|||135 North Street Roodepoort^Johannesburg^Johannesburg2169^ZA||TheUserdutoit@gmail.com^^^^^^^^^^^0847587514

REQUEST WITH PRN WITH HYPHENS

MSH|^~\&|TEST_HARNESS|TEST|CR1|MOH_CAAT|20090226131520-0600||QBP^Q22^QBP_Q21|TEST-CR-14-30|P|2.5
QPD|Q22^Find Candidates^HL7|8494764101303661668890645833527|@PID.3.1^165-676-3727~@PID.3.4.1^DOH~@PID.3.5^MR~@PID.3.6.1^242815
RCP|I

MSH|^~\&|HPRS|HPRS|TEST_HARNESS|TEST|201809261234||RSP^K22^RSP_K21|1539592558257293|P|2.5
MSA|AA|TEST-CR-14-30
QAK|8494764101303661668890645833527|OK
QPD|Q22^Find Candidates^HL7|8494764101303661668890645833527|@PID.3.1^165-676-3727~@PID.3.4.1^DOH~@PID.3.5^MR~@PID.3.6.1^242815
PID|||c0e82356-e510-11e5-a5a3-53cc0a9ce617^^^HPRS_PATIENT_UUID&test-hie.health.gov.za&DNS~9109199019099^^^DHA&www.home-affairs.gov.za&DNS^NNZAF~165-676-3727^^^DOH&www.health.gov.za&DNS^NH20160308~C-267^^^DOH&www.health.gov.za&DNS^MR^242815~165-676-3727^^^DOH&www.health.gov.za&DNS^MR^282515~165-676-3727^^^DOH&www.health.gov.za&DNS^MR^475542||Brooks^Corey^^^^^U||19910919|F|||MandyimbaPRETORIA^0001^ZA
NK1|1|brownkin^gloriakin^^^^^U|SIS^Sister|135 Boland Rd Roodepoort^^^^^ZA||^^^^^^^^^^^0847587514

REQUEST WITH PRN — NO PATIENTS FOUND (NF RESPONSE)

MSH|^~\&|TEST_HARNESS|TEST|CR1|MOH_CAAT|20090226131520-0600||QBP^Q22^QBP_Q21|TEST-CR-14-30|P|2.5
QPD|Q22^Find Candidates^HL7|8494764101303661668890645833527|@PID.3.1^0571472263~@PID.3.4.1^DOH
RCP|I

MSH|^~\&|HPRS|HPRS|TEST_HARNESS|TEST|201809261240||RSP^K22^RSP_K21|1539592708134533|P|2.5
MSA|AA|TEST-CR-14-30
QAK|8494764101303661668890645833527|NF
QPD|Q22^Find Candidates^HL7|8494764101303661668890645833527|@PID.3.1^0571472263~@PID.3.4.1^DOH

REQUEST WITH IDNUMBER (Multiple responses)

MSH|^~\&|TEST_HARNESS|TEST|CR1|MOH_CAAT|20090226131520-0600||QBP^Q22^QBP_Q21|TEST-CR-14-30|P|2.5
QPD|Q22^Find Candidates^HL7|8494764101303661668890645833527|@PID.3.1^6610280162082~@PID.3.4.1^DHA~@PID.3.5.3^NNZAF
RCP|I

MSH|^~\&|HPRS|HPRS|TEST_HARNESS|TEST|201809261242||RSP^K22^RSP_K21|1539592764850339|P|2.5
MSA|AA|TEST-CR-14-30
QAK|8494764101303661668890645833527|OK
QPD|Q22^Find Candidates^HL7|8494764101303661668890645833527|@PID.3.1^6610280162082~@PID.3.4.1^DHA~@PID.3.5.3^NNZAF
PID|||1b081000-f878-11e6-974b-cb1eb5d2a38a^^^HPRS_PATIENT_UUID&test-hie.health.gov.za&DNS~6610280162082^^^DHA&www.home-affairs.gov.za&DNS^NNZAF~105-466-1937^^^DOH&www.health.gov.za&DNS^NH20170221~105-466-1937^^^DOH&www.health.gov.za&DNS^MR^735042||dasda^Ethan^^^^^U||20100202|F|||120 North Street^^^^^ZA
PID|||b0c3920a-8ae5-11e6-9c22-0b1c04bd7897^^^HPRS_PATIENT_UUID&test-hie.health.gov.za&DNS~6610280162082^^^DHA&www.home-affairs.gov.za&DNS^NNZAF~154-199-1020^^^DOH&www.health.gov.za&DNS^NH20161005~154-199-1020^^^DOH&www.health.gov.za&DNS^MR^371924~154-199-1020^^^DOH&www.health.gov.za&DNS^MR^833442~154-199-1020^^^DOH&www.health.gov.za&DNS^MR^475542~154-199-1020^^^DOH&www.health.gov.za&DNS^MR^577133~154-199-1020^^^DOH&www.health.gov.za&DNS^MR^625251~154-199-1020^^^DOH&www.health.gov.za&DNS^MR^687651||Khumalo^Demo Name^^^^^U||20140610|F|||1 Roodepoort^Johannesburg^Johannesburg2169^ZA||TheUserdutoit@gmail.com^^^^^^^^^^^0847587514
PID|||e5ced406-e512-11e5-abc1-63660d354159^^^HPRS_PATIENT_UUID&test-hie.health.gov.za&DNS~6610280162082^^^DHA&www.home-affairs.gov.za&DNS^NNZAF~157-147-2263^^^DOH&www.health.gov.za&DNS^NH20160308~157-147-2263^^^DOH&www.health.gov.za&DNS^MR^371924~157-147-2263^^^DOH&www.health.gov.za&DNS^MR^942124~157-147-2263^^^DOH&www.health.gov.za&DNS^MR^735042~157-147-2263^^^DOH&www.health.gov.za&DNS^MR^833442~157-147-2263^^^DOH&www.health.gov.za&DNS^MR^625251~157-147-2263^^^DOH&www.health.gov.za&DNS^MR^687651~157-147-2263^^^DOH&www.health.gov.za&DNS^MR^475542||Marais^Elliot^^^^^U||19661028|F|||135 North Street Roodepoort^Johannesburg^Johannesburg2169^ZA||TheUserdutoit@gmail.com^^^^^^^^^^^0847587514
PID|||f48f0fc8-565a-11e7-9df3-831b79e6c3fb^^^HPRS_PATIENT_UUID&test-hie.health.gov.za&DNS~6610280162082^^^DHA&www.home-affairs.gov.za&DNS^NNZAF~174-161-2251^^^DOH&www.health.gov.za&DNS^NH20170621~8^^^DOH&www.health.gov.za&DNS^MR^242815||Booi^Name1^^^^^U||20100202|F|||134124 Roodepoort^Johannesburg^Johannesburg2169^ZA||TheUserdutoit@gmail.com^^^^^^^^^^^0847587514
PID|||35be7600-894c-11e6-a585-ff142c548652^^^HPRS_PATIENT_UUID&test-hie.health.gov.za&DNS~6610280162082^^^DHA&www.home-affairs.gov.za&DNS^NNZAF~110-965-2352^^^DOH&www.health.gov.za&DNS^NH20161003~110-965-2352^^^DOH&www.health.gov.za&DNS^MR^833442~110-965-2352^^^DOH&www.health.gov.za&DNS^MR^577133~110-965-2352^^^DOH&www.health.gov.za&DNS^MR^625251~110-965-2352^^^DOH&www.health.gov.za&DNS^MR^282515~110-965-2352^^^DOH&www.health.gov.za&DNS^MR^397460~110-965-2352^^^DOH&www.health.gov.za&DNS^MR^475542~110-965-2352^^^DOH&www.health.gov.za&DNS^MR^687651~110-965-2352^^^DOH&www.health.gov.za&DNS^MR^371924~110-965-2352^^^DOH&www.health.gov.za&DNS^MR^942124~110-965-2352^^^DOH&www.health.gov.za&DNS^MR^735042||joseph^Nosisi^^^^^U||20110303|F|||Ngqongweni Roodepoort^Johannesburg^Johannesburg2169^ZA||TheUserdutoit@gmail.com^^^^^^^^^^^0847587514
NK1|1|noksurname^nokfirstname^^^^^U|SIS^Sister|135 Boland Rd Boland Rd^Roodepoort^Johannesburg2169^ZA||^^^^^^^^^^^0847587514

REQUEST TOO VAGUE (AE RESPONSE)

MSH|^~\&|TEST_HARNESS|TEST|CR1|MOH_CAAT|20090226131520-0600||QBP^Q22^QBP_Q21|TEST-CR-14-30|P|2.5
QPD|Q22^Find Candidates^HL7|8494764101303661668890645833527|@PID.5.1.1^bo*@PID.5.2^na*@PID.8^F
RCP|I

MSH|^~\&|HPRS|HPRS|TEST_HARNESS|TEST|201809261248||RSP^K22^RSP_K21|1539592979931125|P|2.5
MSA|AE|TEST-CR-14-30
ERR|||207|E||||wildcard query is too vague, surname length should be at least 4 chars plus wildcard
QAK|8494764101303661668890645833527|AE
QPD|Q22^Find Candidates^HL7|8494764101303661668890645833527|@PID.5.1.1^bo*@PID.5.2^na*@PID.8^F

POINTS TO NOTE:

1. A request by parameter PRN will only ever return one patient.
2. If the PRN was allocated remotely and has not yet been synched from local to central, a search to central will not return a patient for that PRN. However a search to local will return that patient.
3. A patient may have multiple PRNs.
4. A search by NNZAF number (SA idnumber) may return multiple patients.

Sandbox

hprsintegrationv1.10

HPRS integration sandbox details

Author: Kirsten du Toit — Version: 1.0 — Date: 19/03/2019

HPRS INTEGRATION SANDBOX ACCESS

CREATE A PATIENT TO SEARCH FOR ON THE HPRS WEBEND:

URL: https://test-hie.health.gov.za/

Username: Mede_Mass Password: 6jrzF2f7

1. Login
2. Select "facility settings" from drop down menu for "Administration"
3. Register your PC to a certain facility by either searching for it and then selecting it, or browsing through the facility tree (for example 'bhele')
4. Please note you will need to use the DOH 6 digit facilityid associated with this facility when querying via pdq.
5. Bhele: 735042
6. Register a visit
7. Take note of the new patient's Patient Record Number, their ID number.

Hook Notification:

HPRS provides a hook on the successful registration of a visit that posts the following information to the below url:

Request URL: https://127.0.0.1:4720/

Form Data:

firstname: Name
surname: Surname
HPRN: 1346541529
prnfile:
idNumber: 2110280162082
hprs_uuid: 617a6c92-bb8b-11e6-acc0-838a7c0786d3

The integrating application will be able to listen for this https post and then make a pdq request based on the information passed in the post. The post url is https because browsers do not allow http requests within https environments.

PDQ ACCESS:

All PDQ requests whether to HPRS central or to HPRS local use Mutual TLS Https (see separate document 'ER7 over HTTPS' for details). Health-interop is setup to work with both mutual TLS (certificate that we sign for you) and without mutual TLS (still using https, but not sending a certificate). Note that this is only for testing. A certificate is REQUIRED for connection to production central.

Secured HTTPS traffic (Mutual TLS): URL: https://test-hie.health.gov.za/pdq

Use the Patient Idnumber, HPRS uuid, FileNumber, PRN or demographics to query via pdq.

WORKING PDQ EXAMPLES: See separate document

TEST TOOL: POSTMAN in order to create an http post for testing the PDQ query and response.

Integration Methods

The following integration methods are available for testing on health-interop:

Service name	Protocol	Port Number
hprs-local-pix-pdq-service (no longer supported)	MLLP	2575
hprs-local-pix-pdq-service-tls (no longer supported)	MLLP TLS	2576
hprs-local-pix-pdq-service-https	HTTPS	443

There are 3 methods of sending pdq requests:

1. Unsecured MLP traffic: URL: test-hie.health.gov.za:2575
2. Secured MLP traffic: URL: test-hie.health.gov.za:2576
3. Secured HTTPS traffic (Mutual TLS): URL: https://test-hie.health.gov.za/pdq

For the purposes of testing, mutual TLS is optional in order to test against https://test-hie.health.gov.za/pdq. However a certificate is required for connection to production HPRS central or facility versions.

Transports and Protocols

V2.5 HL7 Communication standard

Overview: http://art-decor.org/decor/services/ProjectIndex?prefix=ad4bbr-&format=html&language=en-US (Project Index HL7 V2.5 International)

See also: https://en.wikipedia.org/wiki/Health_Level_7

The HL7 version 2 standard (also known as Pipehat) has the aim to support hospital workflows. It was originally created in 1989. HL7 version 2 defines a series of electronic messages to support administrative, logistical, financial as well as clinical processes. Since 1987 the standard has been updated regularly, resulting in versions 2.1, 2.2, 2.3, 2.3.1, 2.4, 2.5, 2.5.1 and 2.6. The v2.x standards are backward compatible (e.g., a message based on version 2.3 will be understood by an application that supports version 2.6).

HL7 v2.x messages use a non-XML encoding syntax based on segments (lines) and one-character delimiters. Segments have composites (fields) separated by the composite delimiter. A composite can have sub-composites (components) separated by the sub-composite delimiter, and sub-composites can have sub-sub-composites (subcomponents) separated by the sub-sub-composite delimiter.

The default delimiters are vertical bar or pipe (|) for the field separator, caret (^) for the component separator, and ampersand (&) for the subcomponent separator. The tilde (~) is the default repetition separator.

Each segment starts with a 3-character string which identifies the segment type. Each segment of the message contains one specific category of information. Every message has MSH as its first segment, which includes a field that identifies the message type.

The message type determines the expected segment types in the message. The segment types used in a particular message type are specified by the segment grammar notation used in the HL7 standards.

Example (admission message):

MSH|^~\&|MegaReg|XYZHospC|SuperOE|XYZImgCtr|20060529090131-0500||ADT^A01^ADT_A01|01052901|P|2.5
EVN||200605290901||||200605290900
PID|||56782445^^^XYZ UAReg^PI||KLEINSAMPLE^BARRY^Q^JR||19620910|M||2028-9HL70005^RA99113^^^99DEF^AN|260 GOODWIN CREST DRIVE^BIRMINGHAM^AL^35209^^M~NICKELL'S PICKLES^10000 W 100TH AVE^BIRMINGHAM^AL^35200^^O
PV1||I|W^389^1^UABH^^^^3^^^V VISIT|E||||13579^POTTER^SHERMAN^T^^^MD^0010^UAMC^L|||||||||||||||||||||||||||200605290900
OBX|1|NM|^Body Height||1.80|m^Meter^ISO+|||||F
OBX|2|NM|^Body Weight||79|kg^Kilogram^ISO+|||||F
AL1|1||^ASPIRIN
DG1|1||786.50^CHEST PAIN, UNSPECIFIED^I9|||A

(Note: the PV1/attending-physician portion of this sample message is reconstructed from a somewhat garbled source and may not be exactly byte-for-byte identical to the original.)

Article Sources and Contributors

V2.5 HL7 Communication standard — Contributors: Kdutoit, Kvdwalt, RAlberts

ER7 over HTTPS

ER7 OVER HTTPS

Author: Kirsten du Toit — Version: 1.0 — Date: 19/03/2019

Communications Protocol

The only currently supported transport protocol is ER7 over HTTPS secured with mutual TLS, i.e. a pipe-hat message set as the body of an HTTPS request that is secured with a certificate and key as allocated by HPRS.

ER7 over HTTPS

ER7 over HTTP Draft Specification: https://hapifhir.github.io/hapi-hl7v2/hapi-hl7overhttp/specification.html

ER7 communications can also be sent via https, also secured using Mutual TLS Authentication. Before testing can take place, the testing client will need to be allocated an SSL certificate that the testing client machine will use to establish the https socket connection.

If the body of the HTTPS message contains a valid PDQ request and is accepted by the server, then a 200 OK response containing the HL7 response will be returned.

HL7 PROCESSING ERROR

If there is an error within the HL7 processing, the HL7 error acknowledgement code will be supplied within the HL7 message within the body of a 200 OK HTTPS response.

HL7 acknowledgement codes

The HL7 protocol defines four non-successful acknowledgement codes:

• AR (Application Reject)
• AE (Application Error)
• CR (Commit Reject)
• CE (Commit Error)

When a receiving application produces an HL7 response payload containing one of these status codes, this is considered a successful interaction at the transport layer, and a response code of "HTTP/1.1 2xx" MUST be used.

HTTP TRANSPORT ERRORS

If there is an error at the HTTP transport layer (routing/authentication problem), a NON-HL7 response will be generated with an error HTTP response code.

If the response status is not HTTP 2xx, the content type MUST NOT be an HL7 payload type. Instead, a textual representation of the transport level error must be provided using an appropriate content type.

Non-2xx status codes are reserved for use in cases where the message was not understood, could not be delivered to the receiving application layer, or the receiving application layer failed to process the message due to an unexpected error condition.

Status Code	Description
400 Bad Request	The server cannot or will not process the request due to an apparent client error (e.g., malformed request syntax, size too large, invalid request message framing, or deceptive request routing).
401 Unauthorized (RFC 7235)	Similar to 403 Forbidden, but specifically for use when authentication is required and has failed or has not yet been provided. The response must include a WWW-Authenticate header field containing a challenge applicable to the requested resource. See Basic access authentication and Digest access authentication. 401 semantically means "unauthenticated," i.e. the user does not have the necessary credentials. Note: some sites incorrectly issue HTTP 401 when an IP address is banned from a website and that specific address is refused permission to access it.
403 Forbidden	The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource, or may need an account of some sort.
404 Not Found	The requested resource could not be found but may be available in the future. Subsequent requests by the client are permissible.
405 Method Not Allowed	A request method is not supported for the requested resource; for example, a GET request on a form that requires data to be presented via POST, or a PUT request on a read-only resource.
408 Request Timeout	The server timed out waiting for the request. According to HTTP specifications: "The client did not produce a request within the time that the server was prepared to wait. The client MAY repeat the request without modifications at any later time."
413 Payload Too Large (RFC 7231)	The request is larger than the server is willing or able to process. Previously called "Request Entity Too Large".
415 Unsupported Media Type	The request entity has a media type which the server or resource does not support. For example, the client uploads an image as image/svg+xml, but the server requires that images use a different format.
500 Internal Server Error	A generic error message, given when an unexpected condition was encountered and no more specific message is suitable.
502 Bad Gateway	The server was acting as a gateway or proxy and received an invalid response from the upstream server.
504 Gateway Timeout	The server was acting as a gateway or proxy and did not receive a timely response from the upstream server.

MLP (no longer supported)

Communications Protocol

MLLP (Minimal Lower Layer Protocol), also known as Lower Layer Protocol (LLP), is no longer supported for transmitting the HL7 message string (as of HPRS v1.13.0).

A large portion of HL7 messaging is transported by Minimal Lower Layer Protocol (MLLP), also known as Lower Layer Protocol (LLP). For transmitting via TCP/IP, header and trailer characters are added to the message to identify the beginning and ending of the message because TCP/IP is a continuous stream of bytes.

MLLP takes place on a socket connection established between host and client. To conform to the MLLP standard, the ER7 HL7 message (pipehat string) must have header and trailer characters as laid out in the JavaScript example code below.

ENCODER

var options = { encoding: 'utf8' };
var start = new Buffer([0x0B]);
var end = new Buffer([0x1C, 0x0D]);
Encoder.prototype._transform = function(chunk, encoding, callback) {
  this.push(Buffer.concat([start, chunk, end]));
  callback();
};

Security

The socket connection is secured using Mutual TLS Authentication. Before testing can take place, the testing client will need to send the SSL certificate that the testing client machine will be using to establish the socket connection. See example JavaScript code below:

ENCODER WITH TLS

var start = new Buffer([0x0B]);
var end = new Buffer([0x1C, 0x0D]);
var options = {
  key: fs.readFileSync("HPRSPIXPDQ.key.pem"),
  cert: fs.readFileSync("HPRSPIXPDQ.cert.crt"),
  requestCert: true
};

console.log("trying to connect tls on port 8081, 146.64.19.175");
var socket = tls.connect(8081, '146.64.19.175', options, function () {
  console.log('client connected', socket.authorized ? 'authorized' : 'unauthorized');
  var msg = fs.readFileSync('test/files/IHE-transactions/ITI-21-query-demographics-by-id.er7');
  msg = msg.toString().replace('\n', '\r');
  socket.write(start + msg + end);
});
socket.setEncoding('utf8');

Normal Points of message definition conformance failure:

1. Missing Requesting application in message header.
2. Missing Integrator name in message header.
3. Missing Requesting facility in message header.
4. Missing Security field in message header.
5. Missing ATNA logging.
6. Inability to handle Error cases.