Part II: Transform custom healthcare messages to HL7

In part I of this article, we have already learned more about HL7, its messages, structure, segments, and fields. In this part II, we will show you how to transform proprietary/custom data into HL7 using IRIS for Health. For our sample, we used the data generated by the SYNTHEA bulk data generation project (https://synthea.mitre.org/downloads). So, we will show you how to convert 1000 patients from a CSV file to HL7 v2, using the Interoperability features of IRIS for Health.

Article support application – custom2hl7

You can install the sample application that will be used in this article by following the instructions below:

1. If you want to use ZPM:

• Open IRIS Namespace with Interoperability Enabled.
• Open Terminal and call:

USER>zpm "install custom2hl7"

2. If you wish to utilize Docker:

• Git clone and pull the repo into any local directory:

git clone https://github.com/yurimarx/custom2hl7.git

• Open the terminal in this directory and run:

$ docker-compose build

 

• Run the IRIS container with your project:

$ docker-compose up -d

3. Open the production (http://localhost:32783/csp/user/EnsPortal.ProductionConfig.zen?$NAMESPACE=USER&PRODUCTION=custom2hl7.Custom2hl7Production) and start it (user _SYSTEM and password SYS). It will read patients*.csv and convert it to HL7 v2.

Create a CSV Record Map to get the custom/proprietary data

In the previous step, you ran the production that read the patients3.csv and turned it into SDA. Now, we will do the same with patients4.csv. We could take advantage of the current production, but I would like to demonstrate how to create everything from scratch. So, stop your existing production, and let's do the following:

1. Go to Management Portal (http://localhost:32783/csp/sys/%25CSP.Portal.Home.zen?$NAMESPACE=USER, (make sure you are in the User namespace).
2. Create a CSV Mapper for the patients4.csv from the menu Interoperability > Build > CSV Record Wizard with the values (all other fields are default values):

• Sample file: /home/irisowner/irisdev/csv/in/patients4.csv
• RecordMap name: PatientMap2
• Separator: ,
• Sample should have a header row checked

Note: Select CRLF for Record Terminator

3. Click the button Create RecordMap.
4. As soon as you see the Record Mapper UI, click the button Save As to select the correct package (custom2hl7) and name (PatientMap2) for the Record Map:

5. After saving, the Record Mapper will look like the illustration below:

6. Select BIRTHPLACE and set MAXLEN=200 in the Datatype Parameters field. By default all %String fields store 50 characters, but BIRTHPLACE and ADDRESS need more space. For that reason, adjust the same setting for ADDRESS:

7. Click the Save button and Generate button. Accept default options and click Ok to Generate RecordMap classes.

8. Click Interoperability link (on top) to go to the following tasks:

Create the Data Transformation from Custom to HL7

It is time to use the DTL to build the visual transformation map from custom to HL7.
1. Click Interoperability > Build > Data Transformations > Go button:

2. When you see the Data Transformation Builder, click the New button:

3. Change the Data Transformation Wizard set Package to custom2hl7 and the Name to PatientDTL2:

4. At this point, we will set Source Class. To do that, click the magnifier icon near the Source Class field:

5. Click Message Classes > custom2hl7 > PatientMap2 > Record:

6. At this stage, the Source Class should look like the image below:

7. In the Target Type section, select HL7 radio option and accept Target Class with the value EnsLib.HL7.Message:

8. Pick the Magnifier icon near the Target Document Type and click HL7 Message > 2.3.1 > ADT_A01:

9. Now, when you configured the source and target, click the OK button:

10. Congratulations! We finally have the source and target fields available for visual mapping:

Mapping MSH segment to learn how to use the Mapper UI

In this part, I would like to show you how to map required MSH fields. It will help you learn how to employ the mapper so that you can map other fields as needed.
1. Select FieldSeparator. Then go to Add Action and choose set:

Note: use this procedure when you want to set a fixed value.
2. On Action tab, proceed to Value field and set “|”:

3. Repeat steps 1 and 2 for the following fields and respective values (for the last 3 fields expand the field 9 MessageType):

4. At this point, utilize the message scroller to see more fields (we want to find MessageControlID and ProcessingID). To do that, click the down arrow a few times:

5. Now you should see the following fields:

6. Click ID circle and drop it on MessageControlID field:

7. Do the same for ProcessingID:

8. Finally, expand VersionID and set it to the value “1.0”:

9. Make sure that all fields are mapped according to the table below:

10. Click the Save button and Compile button.

11. Finally, click the Interoperability shortcut to go to the Interoperability menu:

Create the Interoperability Production (the last artifact to complete our work)!

Productions are the mechanisms employed to automate integration flows effectively. So, let's construct our output to transform the patient data in the patients2.csv file to SDA.
1. Click Interoperability > List > Productions:

2. Click the New button:

3. Set custom2hl7 to Package, Patients2Production to Production Name, and Production Type to Generic. Click Ok:

4. Now we have the Production Configuration as shown below:

5. Click the Plus button near Services:

Note: Services are the components used by productions to get source data.

6. Configure the Service Class with the value EnsLib.RecordMap.Service.FileService, and set Service Name to PatientCSVService. Then check Enable Now:

7. Select PatientCSVService and modify the Settings tab with the values mentioned below. When finished, click the Apply button:

• File Path: /home/irisowner/irisdev/csv/in/
• File Spec: patients4.csv
• RecordMap: custom2hl7.PatientMap2
• Target Config Names: PatientProcess

8. Click the Plus button located near Operations:

Note: Operations are production components utilized to write/persist data on a target (databases, systems, API, Web Services, FTP, File, etc.)

9. Configure the Operation with the next values:

• Operation Class: EnsLib.HL7.Operation.FileOperation
• Operation Name: PatientHL7Operation
• Check Enable Now

10. Select the PatientHL7Operation and set the value /home/irisowner/irisdev/csv/out/ to the File Path. Finally, click the Apply button:

11. Click the Plus button next to Processes:

Note: Processes are the production component to coordinate the data flow.

12. Configure the Business Process with the following values:

• Business Process Class: EnsLib.MsgRouter.RoutingEngine
• Routing Rule Name: custom2hl7.PatientRouterRule2
• Business Process Name: PatientProcess
• Check Enable Now

13. So far, we have got all components created:

14. Select PatientProcess and go to Settings tab > Magnifier icon near Business Rule Name:

15. At this time, we will configure the Routing Rule into Rule Editor:

16. Double-click the Rule; configure Source with PatientCSVService and Message Class with custom2hl7.PatientMap2.Record:

17. Click the button +condition:

18. Double click condition and set value 1:

19. Click actions and press button + send:

20. Double click send; set Target with PatientHL7Operation and Transform with custom2hl7.PatientDTL2:

21. Now, you have your Rule definitions ready:

22. Click the Save button and Compile button. Close the browser tab for Rule editor.
23. At this point, we will run our new Production, so click the Start button:

24. Pick PatientProcess and go to the Messages tab to see the results (messages):

25. Click a message to witness a Sequence Diagram with the transformation results:

As you can see, it is an easy and fully visual drag-and-drop process which transforms custom messages to HL7 or other formats. Learn more about it by checking the links mentioned below:

• Building Basic FHIR Integrations with InterSystems IRIS for Health: https://learning.intersystems.com/course/view.php?id=1959&ssoPass=1
• Learn HealthShare for Developers and System Integrators: https://learning.intersystems.com/course/view.php?id=26&ssoPass=1
• Building Business Integrations with InterSystems IRIS: https://learning.intersystems.com/course/view.php?id=1437&ssoPass=1
• Building Basic HL7 Integrations with InterSystems: https://learning.intersystems.com/course/view.php?id=1350&ssoPass=1

 

Bonus: use IRIS to learn more about HL7 messages

1. To know more about HL7 messages, segments and fields, go to Interoperability > Interoperate > HL7 v2.x and click HL7 v2.x Schema Structures:

2. On HL7 Schemas click 2.3.1:

3. You can navigate between message types and read everything you find intriguing. For instance, click ADT_A01 and check its segments:

4. Double Click PID segment and study field’s documentation: