HL7 QuickStart

20 minutes

InterSystems IRIS for Health™ provides a platform for building scalable applications for healthcare interoperability. Each instance of InterSystems IRIS for Health comes with:

  • An integration engine for routing and transforming HL7® messages
  • An API Management tool for automating API endpoint creation
  • Security Management tools for multiple users and roles
  • A multi-model database for resource storage and retrieval
  • Data analytics capabilities for making sense of HL7 messages

For this activity, you will review and launch an HL7 application that is capable of receiving HL7 messages. The application has been built for a small clinic that needs to route messages among their registration, research, lab, and billing facilities. Their application performs the following tasks:

  • Watches an inbound file folder for HL7 messages coming from registration
  • Modifies incoming messages with updated information about the time
  • Routes updated messages to several endpoints:
    • Registered patient info is saved to a database along with the current time.
    • Observation requests are sent to the clinic’s lab.
    • Billing-related information is sent to an external billing service.
If you don’t have InterSystems IRIS set up yet, get a free development sandbox here.

Launch a preconfigured container with a running HL7 application

Click the above link to launch the development sandbox, which includes a temporary instance and built-in IDE. No knowledge of coding is necessary to complete this tutorial, as the Learning Labs contain all of the code you will need.

Send an HL7 message to the application for transformation and routing

  1. Locate the shared/ directory in the project files. The shared folder is mapped to share data with a directory within the InterSystems IRIS for Health instance.
  2. Copy the HL7 message ADT_A01.txt from the shared/quickstarts-hl7/data/sample_data/ directory to the shared/quickstarts-hl7/data/registration/ directory. The message should disappear from the registration/ directory upon being processed by the production.
  3. Find the directory shared/quickstarts-hl7/data/archive/ and notice that the incoming message has been copied here for future reference. Locate the shared/quickstarts-hl7/data/billing/ directory and the shared/quickstarts-hl7/data/lab/ directory, which should contain outgoing HL7 messages. As you can see, the production has transformed the message differently for each endpoint. You can verify this by opening the messages in a text editor and comparing them.

Explore the HL7 application to track and view HL7 messages

  1. The Management Portal is the landing page for managing any InterSystems IRIS instance. Log in using the InterSystems IRIS username and password provided above. In the Learning Labs, click InterSystems > Management Portal in the IDE header bar.
  2. In the header bar of the Management Portal, switch namespaces to INTEROP. Navigate to the Production Configuration interface by navigating to Interoperability > Configure > Production. If the HL7QS.Production is not already running, click Start at the top of the page. This production has been built from the HL7 production template provided with all instances of InterSystems IRIS for Health. Here, you can develop and monitor the pieces of the HL7 production and the messages that are processed by it. Notice there are three columns: Services, Processes, and Operations. The architecture of this application follows from the standard architecture of an InterSystems IRIS for Health production. As you can see below, the leftmost column contains the services for data input, the middle column contains data transformation and routing, and the rightmost column handles data output.
    Production Configuration screen as described above.
  3. In the Message Viewer, you can see the HL7 messages that have been passed between components. Select the business service fromRegFile, and then click the Messages tab in the right-most pane. Click Go to Message Viewer. Select one of the messages that was sent. Now click the Contents tab, where you can see the full contents of the incoming HL7 message. Note that the raw text of the input file has been interpreted based on a designated HL7 schema. Clicking on a field will bring you to the schema definition.
    Message Viewer screen showing both open sessions
  4. With a message selected in the Message Viewer, select Trace > View Full Trace. This contains a diagram of all of the messages, services, processes, and operations in a single session of this production — that is, all the events resulting from a given call to fromRegFile.
  5. Let’s look at the SQL Explorer to make sure PatientRegDBOperation has saved the information extracted from the HL7 message. Return to the Management Portal, ensure the namespace is INTEROP, navigate to System Explorer > SQL. When data has been created or objects have been saved, the tables may be viewed here. In the Execute Query tab, retrieve the PatientReg data by executing the following query:Select * from HL7QS.PatientRegThe table only includes a few columns with data extracted from the HL7 message.
  6. Now you have seen a simple way to process HL7 data using InterSystems IRIS for Health. The application accepts HL7 data, transforms it, and routes it to several endpoints. Using the Management Portal interfaces, you can easily trace the flow of data through the application and view the contents of a message as it is processed. Further resources are located on the InterSystems learning site and the InterSystems documentation website.

Watch it happen

Watch a demonstration of the exercise above.