Smile Guide: HL7 v2 Walkthrough

V. Instructions for Windows

1. Start your instance of Smile CDR, then open your web admin console. 

   
   
   

2. Add HL7 V2.x Listening Endpoint from Admin Console.

    

   
   
   

3. Navigate to the In the configuration page, define the HL7 V2.x Listening Port number. In this case, we will be using port 9201. 

   
   

   
   
   

4. Configure the Persistence module used for FHIR Storage Module

   
   
   

   

   
   
   

5. Save the configuration and restart the Module.

   
   
   

6. Open this link in your browser. 

   
   
   

7. Copy the ORU sample message and paste it into a new VS Code file:

    

   
   
   

8. Click the F1 key. In the search bar that comes up, type “HL7 Tools: Send Message,” then hit enter.

   
   
   
   

9. In the text bar that appears, type the following, then hit enter:

    

   
   

                                                        localhost:9201

   
   
   

   The section highlighted in yellow is the base URL for the FHIR server. In this example, localhost is used. However, be sure to change this (if necessary) to whatever FHIR server URL you are using.

    

   The section highlighted in green is the port number you selected in Step 3. If you chose to use a different port number, replace this green section with that number and remember it for future steps in this process.

    

   

    

   You should expect an ACK (acknowledge) message in your output console. It will look something like this:

    

   

   
   
   

10. Now we must verify the message transaction occurred successfully by checking the transaction history in our Smile CDR web admin console. To do so:

     

    1. Open and login to your Smile CDR web admin console

       
       
       

    2. Click on runtime>transaction log

        

       

       
       
       

    3. You should see a list of transactions. Click on the most recent transaction:

        

       

       
       
       

    4. If you scroll down to Persistence, you’ll notice the body of the bundle that you ingested.

        

        

       Note: if your bundle doesn’t look like the JSON body below, click on pretty print to make it more readable. 

        

       

VI. Instructions for Mac OS

There are multiple ways of ingesting HL7 V2 messages on Mac. The first approach makes use of smileutil and can be operated out of your computer’s terminal application. The second approach requires VS Code as a text editor, along with an associated HL7 Tools extension. Both approaches will lead to the same outcome, they are simply listed below for your convenience, such that you may select whichever approach you are more comfortable with.

Approach 1: Using Smileutil

1. Start your instance of Smile CDR

   
   
   

2. Add HL7 V2.x Listening Endpoint from Admin Console

   
   
   

3. Navigate to the In the configuration page, define the HL7 V2.x Listening Port number. In this case, we will be using port 9201

    

   
   
   

4. Configure the Persistence module used for FHIR Storage Module

   
   
   
   

5. Save the configuration and restart the Module

   
   
   

6. Open this link in your browser 

   
   
   

7. Copy the ORU sample message into a text editor:

   
   
   
   

8. Name this file ORURO1.HL7 and save it in the same directory as your Smile CDR folder. Note: All files should be  to saved as a “.HL7” format

   
   

9. Open your Command Terminal application and navigate to your Smile CDR folder.

   
   
   

10. Copy and paste the following command into your terminal and press enter. Be sure to make the necessary changes highlighted:

     

    bin/smileutil hl7v2-transmit-flatfile -f "ORURO1.hl7" -h "localhost" -p 19005

     

    
    

    The section highlighted in yellow is the base URL for the FHIR server. In this example, localhost is used. However, be sure to change this (if necessary) to whatever FHIR server URL you’re using.

     

    
    

    The section highlighted in green is the name of the URO message file we saved in Step 3. If you saved this file as a different name, replace the green section with that name. 

     

    
    

    The section highlighted in blue is the port number we configured in Step 3 of the Message Ingress Instructions. If you chose to use a different port number, replace the blue section with that number.

    
    
    

11. Now we must verify the message transaction occurred successfully by checking the transaction history in our Smile CDR web admin console. To do so:

     

    1. Open and login to your Smile CDR web admin console

       
       
       

    2. Click on runtime>transaction log

       
       

       
       
       
       

    3. You should see a list of transactions. Click on the most recent transaction:

       
       
       
       
       

    4. If you scroll down to Persistence, you’ll notice the body of the bundle that you ingested

       Note: If your bundle does not look like the JSON body below, click on “pretty print” to make it more readable.

Approach 2: Using HL7 v2 Message Transmitting Tools (Visual Studio + HL7 Tools Plugin)

1. Start your instance of Smile CDR

   
   
   

2. Add HL7 V2.x Listening Endpoint from the Admin Console

   
   
   

3. Navigate to the In the configuration page, define the HL7 V2.x Listening Port number. In this case, we’ll be using port 9201

    

   
   
   

4. Configure the Persistence module used for FHIR Storage Module

    

   
   
   

5. Save the configuration and restart the Module

   
   
   

6. Open this link in your browser

   
   
   

7. Copy the ORU sample message and paste it into a new VS Code file:

    

   
   
   

8. On your keyboard, hold down the fn key, then click the F1 key. In the search bar that comes up, type HL7 Tools: Send Message, then hit enter.

    

   
   
   

9. In the text bar that appears, type the following, then hit enter:

    

   localhost:19005

    

   
   

   The section highlighted in yellow is the base URL for the FHIR server. In this example, localhost is used. However, be sure to change this (if necessary) to whatever FHIR server URL you are using.

    

    

   The section highlighted in green is the port number. If you chose to use a different port number, replace this green section with that number and remember it for future steps in this process.

   
   
   
   

   You should expect an ACK (acknowledge) message in your output console. It will look something like this:

    

   
   
   
   

10. Now we must verify the message transaction occurred successfully by checking the transaction history in our Smile CDR web admin console. To do so:

    
    

     

    1. Open and login to your Smile CDR web admin console.

       
       
       

    2. Click on runtime>transaction log

       
       
       
       
       

    3. You should see a list of transactions. Click on the most recent transaction:

       
       
       
       
       
       

    4. If you scroll down to Persistence, you’ll notice the body of the bundle that you ingested.

       Note: if your bundle does not look like the JSON body below, click on “pretty print” to make it more readable.

       
       

     

Appendix

Reference Links

1. For a list of all supported V2 message types, see the following: HL7 v2.x Support Messages Types

   
   

2. For structure definitions of the supported message types, see the following: HL7 v2.x Support Message Structure

   
   

3. For ADT and ORU sample messages (useful for testing), see the following: Test with HL7 V2 Messages

   
   

4. To read more about using Smileutil to transmit HL7 V2 messages, see the following: HL7 v2.x Transmit Flat File

    

5. To download VS Code, see the following: Downloading VS Code

   
   

To download the HL7Tools extension for VS Code, see the following: HL7Tools