You are using an unsupported browser. Please update your browser to the latest version on or before July 31, 2020.
Welcome to the CAREWare FAQ Page
announcement close button
Home > CAREWare > HL7 Diagnosis Specifications
HL7 Diagnosis Specifications
print icon

This document details how the HL7 Socket Interface imports diagnosis data into CAREWare.  Diagnoses can be imported from ADT, SIU, and BAR messages. Although each message type has multiple trigger events, CAREWare only processes 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 and 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)

Table 1.0: CAREWare's Diagnosis fields


CAREWare Field Description Comments
Diagnosis Date Date of diagnosis  
ICD10/Diagnosis Code Diagnosis Code  
Diagnosis Clinician Clinician name Optional


CAREWare Diagnosis Import


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 diagnosis Import process begins by activating the following indexes:

  • BAR_Map_Provider
  • BAR_Map_Client 
  • BAR_Process_Records 

Upon a successful activation of these indexes, CAREWare then starts processing diagnosis stubs stored in the HL7 Socket holding tank with the status of "Map Provider."


BAR_Map_Provider Index


This index is used to assign the account provided in MSH 6 of the incoming HL7 message to a CAREWare provider. The MSH specifications can be found in table 1.1. CAREWare creates a mapping record if none exists, and if a mapping is complete and an activation code is entered for the provider, the message is moved to the Client Processing step. The Lab Test Mapping Tool’s Map Provider form lists all provider mappings. The Map Provider records indicate whether they are active or inactive. Activation codes are generated and sent out by jProg upon request.


BAR_Map_Client Index


This index is used to match the HL7 message to a CAREWare patient found in the PID segment. The PID specifications can be found in table 1.2. 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 determines 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 a 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.



HL7_Client_Provider_Look_Up_BAR Index


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.


BAR_Process_Records Index

This document focuses on the BAR_Process_Records index. This Index is used to import diagnoses 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. Before importing a diagnosis, CAREWare must know four required elements: the provider, the patient, the diagnosis, and the diagnosis date.  


Table 1.1: MSH Specifications


1 1 R Field Separator   Yes Indicates what delimiter to use to seperate components when parsing.
2 4 R Encoding Characters   Yes  
3 180 O Sending Application   Yes Used in conjuction with MSH 6 to ensure a unique provider mapping record. CAREWare uses this value to determine where the data originated from.
4 180 O Sending Facility   No Available as an alternative to MSH 3.
5 180 O Receiving Application Alternate Provider ID Yes Available as an alternative to MSH 6. If user sets this as the default provider 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 needs 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 uses this field to determine the message type and trigger event. Message type is in MSH 9.0 and trigger event is 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
16 2 O Application
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


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, Middle
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  
7 26 O Date/Time of Birth   No If 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 Gender No Only mandatory if new patient is added.
9 48 O Patient Alias   No  
10 1 O Race Patient Race, Race Subgroup No Single patient race
11 106 O Patient Address Address, Address
Continued, City,
State, Zip
No Address^Address
12 4 B County Code County No  
13 40 O Phone Number - Home Phone No  
14 40 O Phone Number - Business   No  
15 60 O Primary Language   No  
16 1 O Marital Status   No  
17 3 O Religion   No  
18 20 O Patient Account Number acct No  
19 16 O SSN Number - Patient   No  
20 25 O Driver's License Number - Patient   No  
21 20 O Mother's Identifier   No  
22 3 O Ethnic Group Hispanic No  
23 60 O Birth Place   No  
24 2 O Multiple Birth Indicator   No  
25 2 O Birth Order   No  
26 4 O Citizenship   No  
27 60 O Veterans Military Status   No  
28 80 O Nationality   No  
29 26 O Patient Death Date and Time deathDate No  
30 1 O Patient Death Indicator Vtl Status No  


Any fields not defined here can be imported if set to other segments.  If they are set to other segments, those segments must exist in the HL7 message in order to be imported.  If the fields are set and the segments do not exist, CAREWare will error out, stating that it is trying to get data from a segment that does not exist in the message.


Table 1.3: DG1 Specifications


1 4 R Set ID - DG1      
2 2 (B) R Diagnosis Coding Method      
3 60 O Diagnosis Code Diagnosis Code (ICD10 code) Yes  
4 40 B Diagnosis Description      
5 26 O Diagnosis Date/Time Diagnosis date Yes  
6 2 R Diagnosis Type   Yes  
7 60 B Major Diagnostic Category      
8 4 B Diagnostic Related Group      
9 2 B DRG Approval Indicator      
10 2 B DRG Grouper Review Code      
11 60 B Outlier Type      
12 3 B Outlier Days      
13 12 B Outlier Cost      
14 4 B Grouper Version And Type      
15 2 B Diagnosis Priority      
16 60 O Diagnosing Clinician Comment No CW saves the doctor’s name in comments.
17 3 O Diagnosis Classification      
18 1 O Confidential Indicator      
19 26 O Attestation Date/Time      


Sample Update Patient Info Message (Minimum)





(headache)|20171022230000|F||||||||||123456789^Test^Residen t

0 out of 0 found this helpful


scroll to top icon