Home User Manual Discussion Forum Search

Generic HL7

HL7 is the name of the file format that Open Dental uses to synch data with other medical software.  Generic HL7 is an HL7 interface technology built into Open Dental.  These interfaces can be customized to accommodate any software.  There are also more options, such as to use TCP/IP instead of shared folders.  

For the eClinicalWorks (eCW) HL7 interface technology, see eCW HL7 instead.
For LabCorp HL7, see LabCorp HL7.

Messages are used to pass information between Open Dental and the other medical software.  The Open 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 OpenDentalHL7 will need to be installed on the server.  It will handle the interaction between the HL7 messages and Open Dental database.

Open Dental HL7 Interface Specifications (PDF)

Open Dental can send and receive messages from Epic. Contact us for information.

Updating Open Dental Versions
The OpenDentalHL7 service must be stopped before updating Open Dental on the server, then restarted when the update is complete. In version 15.2 or greater, all OpenDent services are automatically stopped prior to an update, then restarted when complete. Prior to version 15.2, you must manually stop and start services. See Updating Open Dental: Stop a Service.

Setup Steps

  1. Make sure the client Open Dental program is installed on the server the same as it would be on any other workstation.

  2. Enable and setup the HL7 message structure.  See Generic HL7 Message Structure.

  3. Connect to the Database:  The information for connecting to the database is in the FreeDentalConfig.xml file in the application folder. This is the same file that the main Open Dental program uses to connect to the database.  The information in the file must be accurate before starting the OpenDentalHL7 service.  One way to ensure the accuracy is to start the Open Dental client program:
    1. On the Choose Database window, set the database connection information. Only simple direct database connections are supported.
      Uncheck the "Do not show this window on startup" box so this window will show the next time you launch Open Dental, then close the window. The connection information should auto-save to the xml file.  If using Vista, Windows 7, or Windows 8, you must right click, Run as Administrator when launching Open Dental or the information you enter will not be auto-saved to the FreeDentalConfig.xml file. 
    2. Verify that the information saved correctly by re-launching Open Dental.  If the information is correct, you can be sure that OpenDentalHL7 will connect to the correct database when the service is started. 

  4. Set up the HL7 Synch Folders (incoming and outgoing).  For Generic HL7 this can be entered on the HL7 Def Edit window.  For Mountainside, click Setup, Program Links, Mountainside to enter. You will most likely set up the folders from the server, so the paths will be relative to the machine you are on.  However, be aware the setup window is viewable from other computers, so from other computers the paths will be invalid.

  5. Create a service to send and receive HL7 messages in the Open Dental Service ManagerIf there are multiple database for multiple customers 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:
    - Verify that the database and HL7 folders are correct (steps 2 and 3).
    - The service will not start if the version is not exactly the same as the version of the main Open Dental program.  
    - If it still won't start, use 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 OpenDentalHL7 will not start.

Troubleshooting
Simple Troubleshooting: If the messages are not being passed to OD and processed as expected, follow the steps below.

  1. Stop the OpenDentalHL7 service.
  2. 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>
  3. Start the service.
  4. In the other medical software, trigger outbound messages. 
  5. Wait about 10 seconds for the message to be processed.
  6. Look in the Windows Log as described in step 4, refreshing as needed.  Verify that the information was processed by Open Dental. Both kinds of messages should result in an insert or update to the patient table. If the message is for a new appointment, the result should also be an insert or update of the appointment table.
  7. After troubleshooting, remove the <HL7verbose>True</HL7verbose> line from the xml file. The line will usually be removed automatically when you click OK from the Choose Database window.

Complex Troubleshooting: First perform the Simple Troubleshooting steps above. If that does not solve the problem, follow the steps below. 
Note:  These steps do not apply if using TCP/IP.  Instead use Windows logs or Message History.

  1. Turn off OpenDentalHL7.
  2. Locate the incoming and outgoing folder paths as set on the HL7 Def Edit window.
  3. Open the outgoing folder in Windows.
  4. In the other medical software, trigger outbound messages. 
  5. Look for the message in the outgoing folder.  You may need to wait up to 60 seconds for the message to appear.
    - If it does not appear, the HL7 service is not set up properly in the other software to create files.
    - If it does appear, make a copy of the message for later analysis.
  6. Start OpenDentalHL7.
    - If the original message does not disappear, then there is a problem with OpenDentalHL7. Look in the Windows Log for errors with the message processing.
    - 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, should be sent to Open Dental programmers for testing.

Also, see HL7 Unit Tests.

 

Open Dental Software 1-503-363-5432