HL7 Medications Import

The purpose of this document is to show how CAREWare imports medications through the HL7 feed interface. Currently the design is for a results-only interface. This document focuses on items that are required for medications import through HL7. These key items include the addition of indexes to the CAREWare interface, a designated message type, CAREWare medication fields, the HL7-designated segment that holds the medication record, and CAREWare’s processing of the incoming record. 

 

Three indexes were added to the HL7 feed settings. These are labeled “MDC_Map_Provider”, “MDC_Map_Client”, and “MDC_Process_Records”.  The “MDC _Map_Provider” index allows CAREWare to choose which CAREWare provider to look for the patient in which the data needs to go to. The “MDC_Map_Client” index will allow CAREWare to choose in which provider to look for the patient record where the data should go. The “MDC _Process_Records” index processes all mappings to translate the incoming record to the patient record in CAREWare. 

 

The message type designated as the medication import message is RAS  (Pharmacy/Treatment administration). The message type is located in the MSH segment at position 9.0. CAREWare treats any messages of this type as medications.

How CAREWare processes an HL7 message

Once the HL7 indexes are set to active, CAREWare attempts to parse the incoming HL7 message into document stubs for processing.  It is important to activate all three indexes for a particular import in order to get the data imported.  CAREWare determines whether the message is a valid import record by looking at the MSH 9 for the message type and MSH 9.1 for the trigger event.  If the message type and trigger event match a message type and trigger event pair from a pre-defined list of possible importable messages, CAREWare parses the incoming file.  The MSH specifications can be found in table 1.1.  During parsing, CAREWare sets the primary provider and client values based on the settings the user has set.

 

CAREWare will also split the messages into multiple document stubs if more than one PID segment exists in the message. The PID specifications can be found on table 1.2. CAREWare will split multiple RXE segments into individual document stubs as well. See Table 1.3 for RXE segment specifications. This is done so that it a single record for an individual client is processed independently. Once the document stubs are created, they will have a starting status of “Map Provider.”

Map Provider Index 

This index is used to match the provider ID (MSH 5) to a domain in CAREWare.  CAREWare creates a mapping record if none exists and deletes the messages if the mappings are incomplete or the activation code is not entered.  If a mapping is complete and an activation code is entered for the domain, CAREWare proceeds to update the status to Map Client.  The Lab Test Mapping Tool’s Map Provider form lists out all provider mappings.  The Lab Test Mapping Tool can only be accessed in the Central Administration domain.  It is located in the Administrative Options Menu in the upper right hand corner.  The Map Provider records indicate whether they are active or inactive.  Active means that an activation code has already been registered by CAREWare.  There are no field mappings for this index.  The activation code will be generated by jProg and will be sent out when the site sends a request for one.  The site must know the value in MSH 5 in order for jProg to create the activation code.

Map Client Index 

This index processes client matching using the matching criteria set in the provider mappings.  If the patient record matches the HL7 value and meets the threshold, then it will be updated to Process Records.  If it doesn’t match or does not meet the threshold, the HL7 document stub will be deleted.

Process Records Index 

Once CAREWare extracts the data necessary for an import, it then attempts to import this data as the patient record.  For medications, the designated segment that holds the immunization record is the RXE segment. See Table 1.3 for specifications.  

 

Before the incoming record can be imported as a patient record, CAREWare will have to do a look up and processes according the following logic:

 

• If the incoming medications are already the current active medications, it will just update the messages.
• If the incoming medications are different to what the patient is currently using, it will stop the medications as of the medication start date and start the new medications as of the start date.

 

Table 1.1 MSH Specifications for HL7 socket interface

 

 

SEQ	LEN	OPT	ELEMENT NAME	CAREWare Field	Required For Import	Comments
1	1	R	Field Separator		Yes	Use to know what delimiter to use to separate components when parsing.
2	4	R	Encoding Characters		Yes
3	180	O	Sending Application		Yes	Used in conjunction with MSH 6 to ensure that unique provider mapping record. CAREWare uses this value to determine where the data originated from.
4	180	O	Sending Facility		No	User can set to this value instead of MSH 3.
5	180	O	Receiving Application	Alternate Provider ID	Yes	User can set to this value instead of MSH 6. If user sets this as the default patient identifier, this value will override the value MSH 6. If this is set as the alternate value, it will override MSH 6 if MSH 6 is empty.
6	180	O	Receiving Facility	Primary Provider ID	No	Used in conjunction with MSH 3 to create a unique provider mapping record. CAREWare uses this value to link to a CAREWare provider. jProg will need this value to create an activation code.
7	26	O	Date/Time Of Message		No
8	40	O	Security		No
9	7	R	Message Type		Yes	CAREWare will use this field to determine the message type and trigger event. Message type will be in MSH 9.0 and trigger event will be in MSH 9.1
10	20	R	Message Control ID		No
11	3	R	Processing ID		No
12	8	R	Version ID		No
13	15	O	Sequence Number		No
14	180	O	Continuation Pointer		No
15	2	O	Accept Acknowledgment Type		No
16	2	O	Application		No
			Acknowledgment Type
17	2	O	Country Code		No
18	6	O	Character Set		No
19	60	O	Principal Language Of Message		No

 

Table 1.2  PID Specifications for HL7 Socket Interface

 

SEQ	LEN	OPT	ELEMENT NAME	CAREWare Field	Required For Import	Comments
1	4	O	Set ID - Patient ID		No
2	20	O	Patient ID (External ID)	Primary Client ID	Yes	Default field where CAREWare looks for matching patient value.
3	20	R	Patient ID (Internal ID)	Primary/Alternate Client ID	No	Can be used as matching patient’s identifier. If the user sets this as the default patient identifier, this value will override the value PID 2. If this is set as the alternate value, it will override PID 2 if PID 2 is empty.
4	20	O	Alternate Patient ID - PID	Primary/Alternate Client ID	No	Can be used as matching patient’s identifier. If the user sets this as the default patient identifier, this value will override the value in PID 2. If this is set as the alternate value, it will override PID 2 if PID 2 is empty.
5	48	R	Patient Name	Last Name, First Name, Name	No	If patient name is not set, CAREWare will match patients by matching patient value only. Users must set CAREWare’s threshold (secondary check) to 0,
6	48	O	Mother’s Maiden Name		No	Can be imported as a custom client field
7	26	O	Date/Time of Birth		No	If patient’s date of birth is not set, make sure CAREWare’s threshold (secondary check) is low enough to account for this.
8	1	O	Sex	Gender	No	Only mandatory if new patient is added.
9	48	O	Patient Alias		No	Can be imported as a custom client field
10	1	O	Race	Patient Race	No	Single patient race
11	106	O	Patient Address	Address, Address Continued, City, State, Zip	No	Address^Address Continued^City^State^Zip
12	4	B	County Code	County	No
13	40	O	Phone Number - Home	Phone	No
14	40	O	Phone Number - Business		No	Can be imported as a custom client field
15	60	O	Primary Language		No	Can be imported as a custom client field
16	1	O	Marital Status		No	Can be imported as a custom client field
17	3	O	Religion		No	Can be imported as a custom client field
18	20	O	Patient Account Number	acct	No
19	16	O	SSN Number - Patient		No	Can be imported as a custom client field
20	25	O	Driver's License Number - Patient		No	Can be imported as a custom client field
21	20	O	Mother's Identifier		No	Can be imported as a custom client field
22	3	O	Ethnic Group	Hispanic	No
23	60	O	Birth Place		No	Can be imported as a custom client field
24	2	O	Multiple Birth Indicator		No	Can be imported as a custom client field
25	2	O	Birth Order		No	Can be imported as a custom client field
26	4	O	Citizenship		No	Can be imported as a custom client field
27	60	O	Veterans Military Status		No	Can be imported as a custom client field
28	80	O	Nationality		No	Can be imported as a custom client field
29	26	O	Patient Death Date and Time	deathDate	No	Sets the date of death
30	1	O	Patient Death Indicator	Vtl Status	No	Sets the enrollment status to decease

 

 

Table 1.3  RXE Specifications for HL7 Socket Interface

 

 

SEQ	LEN	OPT	CAREWare Field	Required for Import	ELEMENT NAME	Comments
1	200	R	Med Quantity, Med frequency, Med start and end dates	Yes	Quantity/Timing	CW uses these fields: <quantity (CQ)> ^ <interval (CM)> ^ <duration> ^ <start date/time (TS)> ^ <end date/time (TS)>
2	100	R	Med Definition Code	Yes	Give Code
3	20	R			Give Amount - Minimum
4	20	O			Give Amount - Maximum
5	60	R	Med Units	Yes	Give Units
6	60	O	Med Form	No	Give Dosage Form
7	200	O	Med Instructions	No	Provider's Administration Instructions
8	200	C			Deliver-to Location
9	1	O			Substitution Status
10	20	C			Dispense Amount
11	60	C			Dispense Units
12	3	O			Number of Refills
13	60	C			Ordering Provider's DEA Number
14	60	O			Pharmacist/Treatment Supplier's Verifier ID
15	20	C			Prescription Number
16	20	C			Number of Refills Remaining
17	20	C			Number of Refills/Doses Dispensed
18	26	C			D/T of Most Recent Refill or Dose Dispensed
19	10	C			Total Daily Dose
20	1	O			Needs Human Review
21	200	O			Pharmacy/Treatment Supplier's Special Dispensing Instructions
22	20	C			Give Per (Time Unit)
23	6	O			Give Rate Amount
24	60	O			Give Rate Units
25	20	O	Med Strength	Yes	Give Strength
26	60	O			Give Strength Units
27	200	O	Med Indication, Medication Prophylaxis	Yes	Give Indication	CW uses the two fields for indication and prophylaxis: <identifier (ST)> ^ <text (ST)>
28	20	O			Dispense Package Size
29	60	O			Dispense Package Size Unit
30	2	O			Dispense Method