The purpose of this document is to explain how CAREWare processes information conveyed as HL7 and sent through the CAREWare Socket Interface.  Like all CAREWare import features, the Socket Interface translates source values so that they are compatible with destination fields.  The sources in this case are values from elements in the HL7 message, and these translations are called mappings in CAREWare.

 

The HL7 socket uses a combination of predefined HL7 fields to determine which fields to look at for certain things to match on as well, and it uses a new generic mapping architecture for these translations. The predefined fields are primarily used for provider mapping, client mapping, and import record mappings.  This document focuses on the new generic mapping architecture.  The HL7 Socket currently has been tested with HL7 version 2.3.

 

HL7 Messages Types, Trigger Events, and Indexes

The HL7 socket interface processes seven different types of HL7 messages: ADT, BAR, ORU, VXU, VXR, RAS, DFT and SIU. Although each message type has multiple trigger events, CAREWare will only process those specified below. The HL7 element “Message Type” is found in the MSH segment at position 9. The trigger event is a subfield of this element, which is found at the first subfield 9.1. 

 

The following ADT messages primarily include demographic, insurance, poverty level, and hospital admission data:

• A01 (admit notification)
• A03 (discharge)
• A04 (patient registration)
• A08 (update patient information)
• A11 (cancel)
• A34 (merge patient)
• A35 (merge patient)

The following SIU event types are processed in CAREWare to import appointment, service, and referral data:

• S12 (new appointment)
• S13 (rescheduling)
• S14 (modification)

While CAREWare could import diagnoses from the above ADT and SIU message types, it is recommended to import diagnoses through BAR messages for better processing and reporting. The following message types are allowed:

• P01 (add patient account)
• P02 (purge patient account)
• P03 (post detailed financial transactions) 
• P04 (generate bills and receivable statements)
• P05 (update account)
• P06 (end account)

Labs, screenings, and screening labs are imported from the ORU message type:  R01 (transcribed Reports)

Medications are imported from the RAS messages with event type:

• O01 (order message)

Vaccinations or Immunizations are imported from the following message type:

• V03 (response to query)
• V04 (unsolicited update to the vaccination record)

Services are also imported from the DFT financial transaction messages with event type:  P03 (post detailed financial transaction)

CAREWare's Socket Interface breaks down the import process into distinct steps called Indexes, each defined by specific functionality and an option for activation by admin users.  All messages are initially processed by the Make Stubs index. This index parses the raw HL7 message and takes only the valid messages based on the message type and trigger event.  It creates message stubs, which are representations of the HL7 message that hold the status and fields necessary for processing.  

 

The Map Provider Index creates and uses the provider mappings that associate the HL7 message with a provider in CAREWare. The value CAREWare typically uses to match the message to a provider is found in the Receiving Facility and Sending application element in the MSH segment.   If no value is present for the Receiving Facility element, the user can set up an alternate value by specifying the segment and position in the field mapping section of the HL7_Make_Document_Stubs index.  It takes the alternate value and stores it in the Receiving Facility element when processing begins.  When CAREWare processes this index, it initially creates a mapping record if none exists for this Receiving Facility and Sending Application pair; the message and its stubs are marked for deletion since no activation code or provider specification has been set up for it.  Once a provider mapping is set up and an activation code is entered for this Receiving Facility/Sending Application pair, CAREWare will update the import status to Map Client.

 

The Map Client index is used to match the HL7 message to a CAREWare patient.  The interface uses the Patient ID (External ID) found in the PID segment to identify patients.  The provider mapping specification done in the Map Provider part of the process allows the user to specify which CAREWare field to use for matching.  If the message does not contain a value for the PID element, the user can specify an alternate value using the field mapping in the HL7_Make_Document_Stubs index.

 

In addition to matching the patient based on the value, CAREWare uses a secondary check called the demographic threshold, which considers additional criteria even when the ID matches as described above.  This additional check compares last name, first name, and date of birth, and the threshold set in the provider mappings will determine how closely those demographic elements need to match in order for the record to be considered a match.  When that threshold is not met, the message and all related stubs are marked for deletion. However, CAREWare also has a feature to automatically add new clients based on user configurable setting.

 

In cases where the patient information does not match an existing CAREWare client record, the interface can still import results into an observation provider, which stores data for Ryan White-suspected patients, depending on whether diagnosis and generic condition results meet certain criteria.  For diagnosis conditions, the interface checks for whether or not the patient had a particular diagnosis.  For generic conditions, the user can set the interface to compare any segment element to a user-defined value. 

 

CAREWare also provides optional manual client matching functionality (screenshot below).  Admin users can use this to review and match patient records within the provider that have been identified by the Map Provider process. Once enabled, Manual Client Matching is available across all providers importing data through the HL7 Socket Interface. An option to automatically add clients in case of a mismatch is available as well. It is recommended to use the "Auto-Add Clients" (screenshot below) with great caution because that could potentially increase the clients within the provider to unmanageable levels.

 

 

 

The Process Records Index is used to import specific data into CAREWare. Each message type imports different data into CAREWare. There are checks to make sure that all required data elements needed for particular imports are mapped prior to allowing the import to proceed.  For example, before importing a diagnosis, CAREWare must know four required elements: the provider, the patient, the diagnosis, and the diagnosis date.  The interface resolves the provider and client in the Map Provider and Map Client indexes. The two remaining elements are resolved by mappings in the Process Records index. Once all four are recognized, the import moves forward. 

 

CAREWare also provides an option to match providers and clients in one step using client provider lookup indexes. When using lookup indexes, it is advised not to operate with other Map Provider/Map Client indexes activated to avoid inconsistent provider and client matching functionality. The lookup indexes search for patients across all CAREWare providers and set the provider and client values based on the setup. The following cases are possible:

• No client/provider combination is found: CAREWare automatically adds the client record to a provider according to conditions set on the Fallback Conditions screen (screenshot below).
• A single client/provider record is found: if the client threshold is met, the client is assigned to the provider; otherwise the fallback provider settings are used.
• Several clients in a provider are identified: CAREWare flags the importing client as "Duplicate" and waits for user resolution.
• A single client is found in several providers: values entered for the client custom field for import provider are used for the import; if these are not found, the Primary Provider calculation used in CAREWare's Custom Report module is used.

 

 

In special cases, CAREWare can import services, instead of labs, from ORU messages.

This happens when the ORU segments contain custom built service codes in OBX 3.1.  The relevant indexes created for the service import are PWX_Map_Provider, PWX_Map_Client and PWX_Process_Records.   

 

Generic Mappings

The generic mapping feature offers a way for users to specify any field in the HL7 message as a value they want to associate with a particular client field. CAREWare will use this information to link the values. While this enables the field mappings to be flexible, there are certain restrictions on the flexibility permitted within the processing.

 

Default Mappings

The interface creates some default mappings when a user activates an index. The user can adjust and add to these field mappings as necessary. For example, a user can import appointment records from the HL7 and have them stored as services in the CAREWare client record, and the user can choose which value in the message (a particular doctor’s name, a location, or an insurance type) should be used to map to the CAREWare subservice field. Once CAREWare imports the completed appointment, if no service exists for this appointment, CAREWare will create the service based on the mappings.

 

There are a few default mappings associated with each index (so that users don’t have to start from scratch every time they activate this module). The default mappings also ensure that the fields required to import data into CAREWare are defined.  The tables below list the default mappings associated with each index.  Some indexes do not have default mappings.

 

HL7_Make_Document_Stubs

 

Field Mapping Label	Segment	Position	Usage
Provider_id	MSH	5	Match CAREWare provider
Alt_provider_id	MSH	4	Specifies the provider ID to use if the default value is blank
Match_ptn_id	PID	2	Match patients
Alt_match_ptn_id	PID	4	Specifies the alternate patient identifier to use if default is blank

 

Map_Client Index

 

 

Field Mapping Label	Segment	Position	Usage	Default Values
Map_cl_gnd_rfk	PID	8	Match gender	F = Female M = Male O = Other U = Unknown
Race	PID	10	Match race	W = White B = Black A = Asian I = Indian O = Other U = Unknown
Map_cl_stt_rfk	PID	11.3	Match state
Dgn_dgn_df_fk	DG1	3	Match diagnosis	Has all diagnoses listed in current diagnosis definitions table. Mapping uses ICD10 codes
Diagnosis_Type	DG1	6	Used to filter for final types of diagnosis	A = Admitting W = Working F = Final

 

Process Records ADT

 

 

Field Mapping Label	Segment	Position	Description	Default Values
Map_cl_gnd_rfk	PID	8	Match gender	F = Female M = Male O = Other U = Unknown
Race/Subgroup	PID	10	Match race	W = White B = Black A = Asian I = Indian O = Other U = Unknown
map_cl_hispanic_yes_un_rfk	PID	22	Ethnicity/Subgroup
map_cl_phone	PID	13	Phone
Map_cl_street	PID	11	Street
Address2	PID	11.1	Address continued
Map_cl_city	PID	11.2	City
Map_cl_stt_rfk	PID	11.3	Match state
map_cl_brt_gn_rfk	PID	8	Birth Gender
Mrn	MRG	1	Match previous patient ID
Acct	MRG	3	Match previous account number
Patient_Class	PV1	2	Specifies the patient class field. Used in conjunction with patient type to determine the admission type	E = Emergency I = Inpatient O = Outpatient P = Preadmit R = Recurring B = Obstetrics C = Commercial N = N/A U = Unknown
Patient_Type	PV1	18	Specifies the patient type. Used in conjunction with patient class to determine the admission type	E = Emergency I = Inpatient O = Outpatient P = Preadmit R = Recurring B = Obstetrics C = Commercial N = N/A U = Unknown
Admission_type	PV1	4	Specifies hospital admission type. Used to determine whether or not admission is an emergency visit	A = Accident E = Emergency L = Labor and Delivery R = Routine C = Elective N = Newborn U = Urgent
Dgn_comment	PV1	17.1	Specifies doctors name to be added to comments
Vtl_sg_pk	PID	18	Holds the patient account number. Used to identify a hospital admission
Vtl_sg_date	PV1	44	Holds the date of admission
Vtl_sg_notes	PV2	3.1	Holds the admission reason
dischargeDate	PV1	45	Holds the date of discharge
Dgn_dgn_df_fk	DG1	3	Match diagnosis	Will have all diagnosis listed mapped by ICD10 Codes in current diagnosis definitions table.
Diagnosis_Type	DG1	6	Used to filter for final types of diagnosis	A = Admitting W = Working F = Final
Dgn_date	DG1	5	Used as the diagnosis date

 

POV, INS and ANN_SCR indexes come into effect once an ADT message contains GT1, PV1 and IN1 segments respectively. 

 

Process Records POV 

 

 

Field Mapping Label	Segment	Position	Description	Default Values
pvr_lv_household_income	GT1	27	Household income
pvr_lv_household_size	GT1	28	Household size
pvr_lv_date	PV1	44	Visit date used as poverty level date

 

Process Records INS

 

 

Field Mapping Label	Segment	Position	Description	Default Values
Insurance	IN1	4	Match Insurance Codes	Has all diagnoses listed in CAREWare Insurance table
ins_as_date	PV1	44	Visit date used as insurance assessment date

 

 

 

Process Records ANN SCR

 

 

Field Mapping Label	Segment	Position	Description	Default Values/Comments
tst_tst_df_fk	PV1	3.3	Household income	Available under OBX segment 3.0. All tests available in CAREWare for mapping
tst_qlt_ts_fk	PV1	3.3	Household size	Available under OBX segment 5.0. All relevant result mappings available in CAREWare
tst_date	PV1	44	Visit date used annual screening date

 

Process Records BAR

 

 

Field Mapping Label	Segment	Position	Description	Default Values
Dgn_dgn_df_fk	DG1	3	Match diagnosis	Has all diagnoses listed in current diagnosis definitions table. Mapping uses ICD10 codes
Diagnosis_Type	DG1	6	Used to filter for final types of diagnosis	A = Admitting W = Working F = Final
Dgn_date	DG1	5	Used as the diagnosis date

 

Process Records SCH

 

 

Field Mapping Label	Segment	Position	Description	Default Values
Dgn_dgn_df_fk	DG1	3	match diagnosis	Has all diagnoses listed in current diagnosis definitions table. Mapping uses ICD10 codes
Diagnosis_Type	DG1	6	Used to filter for final types of diagnosis	A = Admitting W = Working F = Final
Dgn_date	DG1	5	Used as the diagnosis date
App_time_scheduled	AIG	8	Used to set the appointment time
Map_sb_sbs_fk	AIG	3	Used to specify the type of subservice for appointment	All subservices for contract based on import provider
App_pk	SCH	1	Used to identify a specific appointment
Visit_Units	SCH	9	Used to update service quantity
Filler_Status_Code	SCH	25	Identifies the status of the appointment	Pending = Pending Waitlist = Waitlist Booked = Booked Started = Started Overbooked = Overbooked DC = DC Deleted = Deleted Blocked = Blocked Canceled = Canceled Complete = Complete

 

Process Records MDC

 

 

Field Mapping Label	Segment	Position	Description	Default Values
mdc_quantity	RXE	1	Used to for quantity
mdc_frq_rfk	RXE	1.1	Used for medication frequency
mdc_start_date	RXE	1.3	Used as the medication start date
mdc_end_date	RXE	1.4	Used as medication end date
mdc_avl_md_fk	RXE	2	Used to specify the type of available medication	All medication definitions based on import provider
mdc_units	RXE	5	Used to specify units
mdc_pd_md_frm_fk	RXE	6	Used to specify medication form
mdc_instructions	RXE	7	Used to specify medication instructions
mdc_strength	RXE	25	Used to specify strength for a medication
mdc_ind_rfk	RXE	27	Specifies medication Indication	All indications available within the provider
mdc_prp_rfk	RXE	27.1	Specified medication prophylaxis	All prophylaxes available within the provider

 

Process Records IMM

 

 

Field Mapping Label	Segment	Position	Description	Default Values
imm_date	RXA	3	Used to retrieve the immunization date
Imm_imm_df_fk	RXA	5	Used the retrieve immunization definition	all immunization definitions available within the provider

 

Process Records PWX

 

 

Field Mapping Label	Segment	Position	Description	Default Values
srv_date	PV1	44	Used to retrieve the immunization date
cnt_sb_pk	ORU	3	Used the subservice contract information	All subservices for contract based on import provider

 

Process Records DFT

 

 

Field Mapping Label	Segment	Position	Description
Transaction ID	FT1	2	Used to add, edit or delete services
srv_date	FT1	4	Service Date
cnt_sb_pk	FT1	7	Service Name
Transaction Description	FT1	8	Service Description
srv_qty	FT1	10	Service Quantity
srv_price	FT1	11	Service Unit price