Convert CSV file to HL7 messages

This tutorial shows you how to create HL7-like messages using a .csv file Caristix software.

When to use this tutorial

We’ve had a lot of questions from users about how to send data from flat files or databases to an HL7 system.  First, we need to keep in mind the HL7 system is expecting messages in a very specific event-based format.   The format would define the list of supported trigger events as well as the list of segments and fields supported for each trigger event.  It would also include attributes such as optionality, repeatability and data length description.  You can even define code sets for specific fields.  In other words, the format is the message specification the system is expecting to receive.

This tutorial explains how to generate valid HL7 messages where data comes from a csv file.

Scroll down to download files used in this tutorial.

Overview

The process is straightforward. First, create a task that includes all the configuration information needed to populate a message template from data sources. To make this example self-contained, we will send the message to a second task. This second task will take the message and save it to a file.  The process then needs to be re-run to process the second (and subsequent) csv file rows.

Here is a step-by-step explanation.

Step #1: Create a suite

1. Create a test suite:

   For the purposes of this tutorial, name the suite Caristix Test Tutorial – Convert csv file to HL7 messages

2. Create a scenario:

   Name the scenario How To

3. Add an action:

   Name the action Generate messages from csv file

4. Create a “Send HL7 Message” task:

   Call this new task Generate message

5. Create a “Receive HL7 Message” task:

   Call it Receive generated messages

Step #2: Configure Message Generation Parameters

In this step, you’ll configure the message template and the data sources to populate the template.

1. Configure the Generate messages task

   • Select the Generate messages task
   • Select the Configuration tab
   • Configure an outbound connection.
     For the purposes of this tutorial, we will not send generated messages to the HL7 system directly but to another internal task (Receive generated messages). So the outbound connection will be bound to  localhost (host is 127.0.0.1 and port is 6661). Set host and port to the HL7 system’s to send the message to the remote system.  Set timeout to 30 seconds.
   • Select it as the Outbound connection

2. Get a message template

   • If you have a single message illustrating what the HL7 system is expecting to receive, paste it in the message zone.  This becomes the message template.  Generated messages will be based on this message.

   – OR –

   • If you don’t have a sample message, start by creating the HL7 system conformance profile.  Several techniques can be used for this.  Refer to the profile creation documentation section to learn more. 
   • Click the Generate message from Profile… button
   • Select the HL7 system conformance profile just created from the Profile library.  For this tutorial, you can use the Caristix Test Tutorial – Convert csv file to HL7 messages.cxp conformance profile provided in the tutorial folder.
   • Select a trigger event.
   • Click OK

    

3. Configure fields

   Now you’re going to set up variables to link .csv file fields (data sources) to HL7 fields (message target).  During execution, the HL7 message fields are populated with data from the data source, so a new message is created for each file row.  Here, the data source will be a .csv file, but it can also be an Excel file or a database.

   • Move the mouse over the HL7 field you want to populate with the first field in the data source
   • Right-click the field and select Set Variable for field
     The variable window opens
   • Click Add…
     A new row is added to set a new variable
   • Rename the variable name
   • Set TYPE to String
   • Under Configuration, set Type to Text File
     
   • Under Generate, select  sequential list
     
   • Set File to your csv file.  For this tutorial, let’s use Tutorials/Data/Patient Demographics.csv provided the tutorial folder.
   • Set Column: 1
   • Set Column delimiter: ,
     Preview updates showing retrieved data from data source
   • Click OK

   Repeat these steps for each field to be linked to the HL7 message template, changing the variable name and column to pick data from.  Once all fields are linked, move to the next step.

Step #3:  Execute

1. Configure the Receive generated messages task

   As explained earlier, for the purpose of this tutorial, we will send generated messages to an internal task. If you want to send messages directly to the remote HL7 system, you can skip this step.

   • Select the Receive generated messages task
   • Select the Configuration tab
   • Configure an inbound connection where host is 0.0.0.0 and port is 6661.  Timeout configuration would be 30 seconds. 
   • Select it as the Inbound connection
   • Check the Save inbound message to file check box
   • Set File path to C:${CxScenarioSuiteName}.hl7
   • Check the Append checkbox so messages are added to the file.

2. Set the scenario to execute several times so several messages are generated

   • Select the Generate messages action in the suite tree
   • Select the Configuration tab
   • Set Execute:  to the number of rows you have in the data source
     The sample data source provided below (Patient Demographics.csv) has 10 rows.  If you’re using this file,  set this number to 10

3. Execute and generate messages

   • Right-click the Generate messages action
   • Select Run

A file (Caristix Test Tutorial – Convert csv file to HL7 messages.hl7) is created with 10 messages in it.

Files used in this tutorial:

• Here is what the Caristix Test Tutorial – Convert csv file to HL7 messages.cxs test suite should look like after completing all steps.
• The Patient Demographics.csv file
• The simple conformance profile Caristix Test Tutorial – Convert csv file to HL7 messages.cxp

Enjoy!