​The purpose of this document is to outline how CAREWare imports immunization records through the HL7 feed interface.   Currently the design is for a results-only interface.  This document focuses on items that are required for immunization import through HL7.  These key items include the addition of new indexes to the CAREWare interface, CAREWare immunization fields, the HL7-designated segment that holds the immunization record, and the parsing of the segment for processing.  

 

There are new indexes on the interface that activate the immunization imports.  These indexes will be labeled “IMM_Map_Provider”, “IMM_Map_Client”, and “IMM_Process_Records.  The “IMM_Map_Provider” index allows CAREWare to choose in which provider to look for the patient record where the data should go. The “IMM_Map_Client” index allows CAREWare to choose which CAREWare patient to link the data to.  The “IMM_Process_Records” index processes all mappings to translate the incoming record to the patient record in CAREWare.

 

​

 

 

CAREWare has seven fields that make up an immunization record. Five of these fields are mandatory and two are optional.

 

Table 1.0 - CAREWare Immunization Fields  

 

CAREWare Field	Description	Comments
Primary/Alternate Provider ID	Key to the CAREWare provider	Established in Map Provider Index Processing
Primary/Alternate Client ID	Key to the CAREWare patient	Established in Map Client Index Processing
Immunization	Key to the CAREWare Immunization definition	Incoming record needs to be mapped to a CAREWare immunization definition.
Immunization Date	Date of immunization
Immunization Received	Key to tell CAREWare that immunization was given.	If user does not specify a mapping for this value, the default value returned is yes.
Immunization History	Key to tell CAREWare the immunization history	Optional field. CAREWare will leave blank if not specified.
Immunization Action	Sets the CAREWare action for the immunization	Possible actions are Add, Update, or Delete

 

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 in table 1.2.  CAREWare splits multiple RXA segments into individual document stubs as well. See Table 1.3 for RXA 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 immunizations, the designated segment that holds the immunization record is the RXA segment.  See Table 1.3 for specifications.

Before the incoming record can be imported as a patient record, CAREWare has to do a lookup.  The purpose of the lookup is to determine if there’s an existing immunization record already present in CAREWare for a particular patient.  This lookup is based on the immunization date, immunization definition, the patient, and the domain in which the patient resides.  If there is a record that matches the date and definition already in CAREWare, it updates the record with the incoming data regardless of the message type, trigger event, or action code.  If it does not find a record, it treats it as a new record unless the action code is a delete action.  If a delete action is set and there’s an immunization record found during lookup, the CAREWare record will be deleted.

 

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 5 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 5. 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 Acknowledgment Type		No
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 identifier. If 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 identifier. If 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,	No	If patient name is not set,
				Middle Name		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. YYYY
8	1	O	Sex	Sex at Birth	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 RXA - CAREWare Field

 

SEQ	LEN	OPT	ELEMENT NAME	CAREWare Field	Required for import	CAREWare Rules
1	4	R	Give Sub-ID Counter		No
2	4	R	Administration Sub-ID Counter		No
3	26	R	Date/Time Start of Administration	Immunization Date	Yes	Can not be future date
4	26	R	Date/Time End of Administration		No
5	100	R	Administered Code	Immunization	Yes	Use your own code. It will be mapped through the CW user interface.
6	20	R	Administered Amount		No
7	60	C	Administered Units		No
8	60	O	Administered Dosage Form		No
9	200	O	Administration Notes		No
10	200	O	Administering Provider		No
11	200	C	Administered-at Location		No
12	20	C	Administered Per (Time Unit)		No
13	20	O	Administered Strength		No
14	60	O	Administered Strength Units		No
15	20	O	Substance Lot Number		No
16	26	O	Substance Expiration Date		No
17	60	O	Substance Manufacturer Name		No
18	200	O	Substance Refusal Reason		No
19	200	O	Indication		No
20	2	O	Completion Status	Immunization Received	No	Use your own code. It will be mapped through the CW user interface. If no value is sent for this field, it will default to a value of Yes.
21	2	O	Action Code	Immunization Action	No	Use your own code. It will be mapped through the CW user interface. Can be used to delete the immunization
22	26	O	System Entry Date/Time		No

Sample Immunization Message (Minimum)    

MSH|^~\&|SENDAPP| | |PROVIDERID|||VXR^V03 

PID|1|125976|||IMM^TESTER||20010101|F 

RXA|0|1|19900607||08^HEPB-PEDIATRIC 

 

Sample Immunization Message (Long) 

  

MSH|^~\&| SENDAPP |SENDFAC|CAREWARE| PROVIDERID 

|20120131201257||VXU^V04|Q695570448T2304762064X135706||2.3 

PID|1|125976|125976||BAR^TESTER||20010101|F||||||||||125976011 

PD1|||CHILDREN=S HOSPITAL^^1234^^^^XX~LEXINGTON CLINIC^^1234A^^^^FI|12345^CARE^ 

PRIMARY^^^DR^MD^^^L^^^DN|||||||03^REMINDER/RECALL - NO CALLS^HL70215|Y 

NK1|1|KENNEDY^JACQUELINE^LEE|32^MOTHER^HL70063||||||||||||||||||||||||||||||898666725^^^^SS 

NK1|2|KENNEDY^JOHN^FITZGERALD|33^FATHER^HL70063||||||||||||||||||||||||||||||822546618^^^^SS 

PV1||R|||||||||||||||A|||V02^19900607~H02^19900607 

RXA|0|1|19900607|19900607|08^HEPB-PEDIATRIC/ADOLESCENT^CVX^90744^HEPB-

PEDATRIC/ADOLESCENT^CPT|.5|ML^^ISO+||03^HISTORICAL INFORMATION - FROM PARENT=S WRITTEN 

RECORD^NIP0001|^JONES^LISA|^^^CHILDREN=S HOSPITAL||5|MCG^^ISO+|MRK12345| 199206|MSD^MERCK^MVX 

RXA|0|4|19910907|19910907|50^DTAP-HIB^CVX^90721^DTAP-HIB^CPT|.5|ML^^ISO+||00^NEW IMMUNIZATION 

RECORD^NIP0001|1234567890^SMITH^SALLY^S^^^^^^^^^VEI~1234567891 

^O=BRIAN^ROBERT^A^^DR^MD^^^^^^OEI|^^^CHILD HEALTHCARE CLINIC^^^^^101 MAIN STREET^^ 

BOSTON^MA||||W46932777|199208|PMC^PASTEUR MERIEUX CONNAUGHT^MVX|||CP|A| 19910907120030 

RXR|IM^INTRAMUSCULAR^HL70162|LA^LEFT ARM^HL70163 

RXA|0|1|19910907|19910907|03^MMR^CVX|.5|ML^^ISO+|||1234567890^SMITH^SALLY^S^^^^^^^^^VEI~1234567891^O=BRIA

N^ROBERT^A^^DR^MD^^^^^^OEI|^^^CHILD HEALTHCARE CLINIC^^^^^101 MAIN 

STREET^^BOSTON^MA||||W2348796456|19920731|MSD^MERCK^MVX 

RXR|SC^SUBCUTANEOUS^HL70162|LA^LEFT ARM^HL70163 

RXA|0|5|19950520|19950520|20^DTAP^CVX|.5|ML^^ISO+|||1234567891^O=BRIAN^ROBERT^A^^DR|^^^CHILD 

HEALTHCARE CLINIC^^^^^101 MAIN STREET^^BOSTON^MA||||W22532806|19950705|PMC^ PASTEUR MERIEUX CONNAUGHT^MVX 

RXR|IM^INTRAMUSCULAR^HL70162|LA^LEFT ARM^HL70163 

NTE|PATIENT DEVELOPED HIGH FEVER APPROX 3 HRS AFTER VACCINE INJECTION 

RXA|0|2|19950520|19950520|03^MMR^CVX|.5|ML^^ISO+|||1234567891^O=BRIAN^ROBERT^A^^DR|^^^CHILD 

HEALTHCARE CLINIC^^^^^101 MAIN STREET^^BOSTON^MA||||W2341234567|19950630| MSD^MERCK^MVX 

RXR|SC^SUBCUTANEOUS^HL70162|LA^LEFT ARM^HL70163 OBX||NM|1648-5^TUBERCULOSIS REACTION WHEAL 3D 

POST 5 TU ID^LN||1|MM||N|||F|||19960418 

 

The sample message (minimum) contains the minimum amount of data for an immunization import.  If no action code (RXA 21.0) is sent, it will treat the immunization as adds or updates only.  The long message can also be processed.  The long message is parsed into several document stubs.  Each stub contains at the very minimum an MSH segment, a PID segment, and a RXA segment.  Any values that are not linked to a field map will be ignored during import.