HL7  

HL7 is the name of the file format that EZ2000 Plus  Dental uses to synch data with other medical software.  There are two different HL7 interface technologies built into EZ2000 Plus Dental:

eClinicalWorks Program Link: These interfaces have been used for years.  They are stable and proven.  They are still used by most customers.

Generic HL7: These interfaces can be customized to accommodate any software.  There are a few more options, such as to use TCP/IP instead of shared folders.

Messages are used to pass information between EZ2000 Plus Dental and the other medical software.  The EZ2000 Plus Dental server will have two shared folders that will be used to pass files back and forth.  A service (program without a user interface) called EZ2000PlusDentalHL7 will need to be installed on the server.  It will handle the interaction between the HL7 messages and EZ2000 Plus Dental database. Start by making sure the client EZ2000 Plus Dental program is installed on the server the same as it would be on any other workstation.

Connecting to the Database
The information for connecting to the database is contained in a file in the application folder called FreeDentalConfig.xml.  This is the very same file that the main EZ2000 Plus program uses to connect to the database.  The information in this file must be accurate before starting the EZ2000 PlusDentalHL7 service.  One way of ensuring the accuracy of this file is to start the ordinary EZ2000 Plus Dental client program and use the Choose Database window to set the database connection information.  Only simple direct database connections are supported.  Warning!  If you are using Vista, Windows 7, or Windows 8, you must right click, run as administrator when running EZ2000 Plus Dental or the information you enter will not be saved to the FreeDentalConfig.xml file.  You can verify that the information saved correctly by launching EZ2000 Plus Dental again.  You must not have checked the "do not show this window on startup" checkbox in the Choose Database window in order to see the information again.   Once the information is correct and verified, you can be sure that EZ2000 PlusDentalHL7 will connect to the correct database when the service is started.

HL7 Folders
See the screenshots of the eClinicalWorks, Mountainside, or Generic HL7 setup windows.  That's where the HL7 folder(s) are set up.  You will most likely be accessing the setup window from the server, so the paths will be relative to the machine you are on.  But beware that the setup window is also viewable from other computers, in which case the paths will be invalid from the other computer.

Service Manager
The EZ2000 Plus Dental Service Manager must be used to create a service to send and receive HL7 messages. If there are multiple database for multiple customers being hosted on one server, then multiple HL7 services, each with unique names, must be setup.  Then, each database must be set up to match with a differently named HL7 service.

Errors
If the service does not start as expected, then check to make sure the database and HL7 folder are correct as explained above. Also, it will not start if the version is not exactly the same as the version of the main OD program.   If it still won't start, look in the Computer Management tool.  My Computer, right click, Manage.  Expand System Tools, Event Viewer, Windows Logs.  Click on Application.  The error and information entries will help determine the reason why the EZ2000 PlusDentalHL7 will not start.

Update Sequence
1. As part of the ordinary update, close EZ2000 Plus Dental on all workstations.
2. This would also be the best time to stop the EZ2000 PlusDentalHL7 service using the tool above (or using any other method).  It is critical to stop the service if you are going to up date the server first.
3. Update one computer to the new version and get EZ running well on that computer.  If you are also using the Middle Tier, you would perform the first update on that computer, which is not necessarily the same computer as the HL7 server or the database server.
4. Update the other computers.
5. At whatever point the HL7 server computer gets updated, the EZ2000 PlusDentalHL7 service absolutely must be stopped first.
6. If you forget to stop it, then stop it and "repair" the EZ installation.
7. Start the service.

Simple Troubleshooting
If the messages are not being passed to EZ and processed as expected:
1. Stop the EZ2000 PlusDentalHL7 service.
2. Make sure your version of Open Dental is at least 7.3.10, 7.4.13, or 7.5.10.  Make sure eCW is at least version 8.0, build 100.17.
3. Edit the FreeDentalConfig.xml file by adding a line for <HL7verbose>True</HL7verbose>.  Example:
<?xml version="1.0" encoding="utf-8"?>
<ConnectionSettings>
   <DatabaseConnection>
      <ComputerName>localhost</ComputerName>
      <Database>opendental</Database>
      <User>root</User>
      <Password></Password>
      <NoShowOnStartup>False</NoShowOnStartup>
   </DatabaseConnection>
   <DatabaseType>MySql</DatabaseType>
   <HL7verbose>True</HL7verbose>
</ConnectionSettings>
4. Start the service.
5. Trigger eCW to create a text file in one of two ways:
---Edit patient information.
---Create a new appointment.
6. In either case, wait about 10 seconds for the message to be processed.
7. Look in the Windows Log as described above, refreshing as needed.  Verify that the information was processed by EZ2000 Plus Dental. Both kinds of messages should result in an insert or update to the patient table. If the trigger was a new appointment, then the message should also result in an insert or update of the appointment table.
8. After troubleshooting, remove the <HL7verbose>True</HL7verbose> line from the xml file. The line will also usually be removed automatically when you click OK from the Choose Database window.

Complex Troubleshooting
1. Perform the Simple Troubleshooting above first. If that does not solve the problem.
2. Turn off EZ2000 PlusDentalHL7.
3.  Look up the paths that are saved in the eCW folder.
4. Open the out folder in Windows.
5. Trigger eCW to create a text file in one of two ways:
---Edit patient information.
---Create a new appointment.
6. In either case, wait up to 60 seconds for the message to appear in the out folder.
7. If it does not appear, then the HL7 service is not set up properly in eCW to create files.
8. If it does appear, make a copy of the message for later analysis.
9. Start EZ2000 PlusDentalHL7.
10. If the original message does not disappear, then there is a problem with EZ2000 PlusDentalHL7. Look in the Windows Log for errors with the message processing.
11. If the message still does not seem to have been processed, then it will need to be debugged.  A copy of the message, and possibly the database itself, will need to be sent to EZ2000 Plus Dental programmers for testing.

HL7 Field Documentation
As of version 11.0.31

MSH - Message Header
Every incoming and outgoing message must have a MSH segment, which is usually the first segment. MSH.8 is required to be the message type field and is composed of two components. Component 1 is the message type (ADT, SIU, DFT, etc.) and component 2 is the event type with the designated component separator between them. A typical MSH.8 field would look like this: SIU^S12 or ADT^A04.

ADT - Demographics Message
PID.2 (eCW internal patient number) is used to determine patient.  If using tight integration, this is stored in the PatNum field in EZ.  If using standalone integration, this is stored in the ChartNumber field in EZ.  If a match is not found, then a new patient is created in EZ.
PID imports LName, FName, MiddleI, Birthdate, Gender, Race, Address, City, State, Zip, HmPhone, WkPhone, Position(marital), and SSN.  If this is a new patient, PriProv is set to practice default.
PID.4 (eCW account number) is saved to the ChartNumber field when using tight integration, but not saved at all when using standalone integration.
PID.22 is parsed for the fee schedule, creating a new one if needed.
PV1 is ignored.
PD1 is ignored.
GT1 is processed to create a guarantor if needed.  The processing is nearly identical as for the PID segment.
IN1 is ignored.

SIU - Scheduling Message
PID.2 (eCW internal patient number) is used as PatNum to determine patient. If match is not found, a new patient is created with that PatNum.
PID is processed to extract 16 various patient demographic fields.
PID.4 (eCW account number) is saved to the ChartNumber field when in tight integration mode.
PV1 is ignored.
SCH.2 (eCW visit number) is used as AptNum to find or create an appointment.  If a found appointment does not match PatNum, error message is shown.
SCH.7 stored in appointment.Note
SCH.11.3 is stored in appointment.AptDateTime
SCH.11.4 (stop time) is used to caculate appointment.Pattern, the length of the appointment.
If AIG segment is present, it is processed for appointment.ProvNum and patient.ProvNum.  A provider is created if needed, based on the eCW alphanumeric provider id. 
If AIG segment is missing, PV1 is processed instead.
AIL is ignored.
AIP is ignored.

DFT - Charge Specification
PID.2 (eCW account Number)
PID.3 (eCW internal patient number)
PID includes an additional 14 patient demographic fields
PV1 includes provider information
PV1.19 (eCW visit number) The AptNum that was originally passed in by eCW.
FT1 A series of segments for all the procedures.
ZX1.5 If this DFT is being used to send a treatment plan, then this is a pdf file, encoded as base64 string. Otherwise, blank.

Also, see HL7 Unit Tests.