Transform custom healthcare messages to SDA
Tags: business, service, interoperability, tutorial
Published: 2023-02-20 18:59:50

<p style="line-height: 1.295; text-align: justify; margin-bottom: 11px;">
  EHR (Electronic Health Record) systems are modeled in a proprietary format/structure and are not based on market models such as FHIR or HL7. Some of these systems can interoperate data in a proprietary format for FHIR and other market models, but others can not. InterSystems has two platforms that can interoperate proprietary formats for market ones: InterSystems HealthShare Connect and InterSystems IRIS for Health. The transformation functionality (DTL - Data Transformation Language) of these platforms can receive data in any format, structure, or communication channel (CSV, JSON, XML, and others via FTP, File, HTTP, etc.) and transform it into market formats directly (FHIR, CDA, HL7 and so on). However, InterSystems has an intermediate format called SDA (Summary Document Architecture) which is used by these platforms to effortlessly generate FHIR STU, R3, R4, HL7v2, HL7v3, and others. In addition, when in SDA format, health data can be persisted in the HealthShare UCR. Thus, first, the proprietary/custom format is transformed to SDA, and then the data can be automatically converted into any market format, as well as saved in HealthShare. In this article, we will show you how to transform proprietary/custom data into SDA using IRIS for Health. The sample data we used was generated by the SYNTHEA bulk data generation project (https://synthea.mitre.org/downloads). We will convert 1000 patients from a CSV file to SDA, using the Interoperability features of IRIS for Health.
</p>

<h2 style="line-height: 1.295; text-align: justify; margin-bottom: 11px;">
  Article support application – custom2sda
</h2>

<p style="line-height:1.295; text-align:justify; margin-bottom:11px">
  Install the sample application that will be used with this article by following the instructions:
</p>

<p style="line-height:1.295; text-align:justify; margin-bottom:11px">
  If you want to install using ZPM:
</p>

<p style="line-height:1.295; text-align:justify; margin-bottom:11px">
  1. Open IRIS Namespace with Interoperability Enabled.<br />2. Open Terminal and call: USER>zpm "install custom2sda"
</p>

<p style="line-height:1.295; text-align:justify; margin-bottom:11px">
  If you want to install using Docker:
</p>

<p style="line-height:1.295; text-align:justify; margin-bottom:11px">
  1. Git clone and pull the repo into any local directory:
</p>

<pre style="line-height: 1.295; text-align: justify; margin-bottom: 11px;">$ git clone https://github.com/yurimarx/custom2sda.git</pre>

<p style="line-height:1.295; text-align:justify; margin-bottom:11px">
  2. Open the terminal in this directory and run:
</p>

<pre style="line-height: 1.295; text-align: justify; margin-bottom: 11px;">$ docker-compose build</pre>

<p style="line-height:1.295; text-align:justify; margin-bottom:11px">
  3. Run the IRIS container with your project:
</p>

<pre style="line-height: 1.295; text-align: justify; margin-bottom: 11px;">$ docker-compose up -d</pre>

<p style="line-height:1.295; text-align:justify; margin-bottom:11px">
  4. Open the production (<a href="http://localhost:52775/csp/healthshare/user/EnsPortal.ProductionConfig.zen?PRODUCTION=customsda.CustomToSDAProduction">http://localhost:52775/csp/healthshare/user/EnsPortal.ProductionConfig.zen?PRODUCTION=customsda.CustomToSDAProduction</a>) and start it. (user _SYSTEM and password SYS). It will read patients.csv and convert it to SDA.
</p>

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

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

1.    Go to Management Portal (http://localhost:52775/csp/sys/%25CSP.Portal.Home.zen?$NAMESPACE=USER, make sure you are in the User namespace).  
2.    Create a CSV Mapper for the patients2.csv. Interoperability > Build > CSV Record Wizard:


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/vz47yff0qg8s0u9ifgf7.png)

**_<span style="font-size:11.0pt" lang="EN-US"><span style="line-height:107%"><span style='font-family:"Calibri",sans-serif'>Note: Select CRLF for Record Terminator</span></span></span>_**

3.    Click Create RecordMap to open the Record Mapper UI and change the Target Classname to customsda.Patients2RecordMap.Record:


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/lcqxzbyuap0a9ooc0srf.png)

4.    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. Do the same for ADDRESS:


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/2jgfv554u1yohwe3jykx.png)

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


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/2oxsj2e50p5bvs1kq2ao.png) 

6.    Click Interoperability to go to the next tasks:


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ivh150h60aa2owfg0hm5.png) 

## Create the Data Transformation from Custom to SDA

It is time to use the DTL to visually build the transformation map from custom to SDA.

1.    Click Interoperability > Build > Data Transformations > Go button:


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ed3eew7jo6z95kfcf21v.png)

2.    You can see the Data Transformation Builder here. Click the New button:


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/vjhr0dnnes81ajmhl15n.png) 

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


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/w9f07ho1lrnax5ee843k.png) 

4.    At this point, we will set Source Class. Click the magnifier icon near the Source Class field:


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/r6t1sglilyw4nrx4me1a.png) 

5.    Click Message Classes > customsda > Patients2RecordMap > Record:


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/i6x8bbpgzhdcms50pyqy.png)

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


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/9yur55g1m8zij5ty3vyq.png) 

7.    In the Target Type section, select XML and accept Target Class with the value EnsLib.EDI.XML.Document:


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/npqtydek7w064cdi5oon.png)

8.    Select the Magnifier icon near the Target Document Type and click XML Document > SDA3_schema > Container:


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/yc47bpkw1y2x6us9zuzs.png) 

Note 1: Container is the root element for all SDA elements, like Patient.

Note 2: for SDA3_schema to be available the following actions are needed:  
Copy SDA3_schema.xsd to your local file system:


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/320dmwhbraqjldbd9nun.png)

Import the SDA3 XSD Schema:


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/sa15nnxqll3evf4wdy65.png)

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


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/eb8eh3qtg7amzer6e50u.png) 

10.    Now we have the source and target fields available for visual mapping:


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/jtc5n07sax6xdyeqvo8m.png)

11.    To create a transformation, you need to drag the circle of the source field and drop it into the arrow of the target field, line by line.


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/8vma5nalj1ej4emi17mn.png)

12.    In the Actions section, you can see the set results:


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/twoerdpe4g6ps3th0nvh.png) 

13.    After mapping all the fields, your actions list will look like this:


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/zqayo07htmfi5vjgzgyq.png) 

Note: for properties with (), you need to set the index because those properties can have more than one item. In this sample we have only one address, so target.{Patient.Addresses(1)….} is configured with 1.

14.    Click the Save button and Compile button.


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/tbztpawxvg52crsgahio.png)

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


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/z4vwdwte8y3d6wc53t0k.png) 

## Create the Interoperability Production, the last artifact to complete our work!

Productions are the mechanisms used to effectively automate integration flows. It’s time to create our output to transform the patient data in the patients2.csv file to SDA.

1.    Click Interoperability > List > Productions:


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/objiea3e2mthfdk9c25f.png) 

2.    Click the New button:

![](/sites/default/files/inline/images/images/image(4438).png) 

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


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/nwbov91xle2cfz4srba1.png)

4.    Now we have the Production Configuration:


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/vj9tju7whgpnhucoboii.png) 

5.    Click the Plus button near Services:


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/2csijzsqs03eh2s0t7q0.png) 

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 Service Name as PatientCSVService, and check Enable Now:


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/h39hw29rlof9pc8omc8p.png)

7.    Select PatientCSVService and configure the Settings tab with

<span style="display: none;"> </span> the values and click the Apply button:  
●    File Path: /opt/user/data/  
●    File Spec: patients2.csv  
●    RecordMap: Patients2RecordMap  
●    Target Config Names: PatientProcess


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/qqiczgi1ynl01qzh560g.png) 

8.    Click the Plus button located near Operations:


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ywfqmsution2a3evaxao.png) 

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

9.    Configure the Operation with these values:  
●    Operation Class: EnsLib.EDI.XML.Operation.FileOperation  
●    Operation Name: PatientSDAOperation  
●    Check Enable Now


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ejtculd4sn31efjnhgkw.png)

10.    Select the PatientSDAOperation and set the value /opt/user/data/ to the File Path and click the Apply button:


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ci4d2x074vq2es2cc9qo.png) 

11.    Click the Plus button next to Processes:


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/3nm279boyubitt3lil9i.png) 

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

12.    Configure the Business Process with these values:  
●    Business Process Class: EnsLib.MsgRouter.RoutingEngine  
●    Routing Rule Name: customsda.PatientRouterRule2  
●    Business Process Name: PatientProcess  
●    Check Enable Now


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/yjnlkjlpx6t0zvq6pjvi.png) 

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


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ygow2aokw96srmfmtsqt.png) 

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


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/6dwtmknqj29tgedsa7ou.png) 

15.    Now we will configure the Routing Rule into Rule Editor:


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/8ix20u6o7hv3ijbvjp79.png) 

16.    Do a double-click on the constraint component and configure Source with PatientCSVService and Message Class with customsda.Patients2RecordMap.Record:


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/nlz7qyxejc9a1qz5382u.png) 

17.    Currently, we have source and target configured:


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ldm3s0w2jdhptu0ypw2l.png) 

18.    Select rule component and click the Green Plus button:


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/i894b3u9bhuv1uxar9sr.png)

19.    Select Send to create a When component:


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/2ykyma06ssbu4s4x1bnw.png) 

20.    Select When component, click the Green Plus button, and select Send component:


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/46z8cvb38kst9k67lg66.png) 

21.    You are supposed to see the picture displayed below on your screen:


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/qx73rqkoct56uldlcl2h.png) 

22.    Do a double-click on the target component and set Configuration Items to PatientSDAOperation, then click the OK button:


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/dc0r8f0mthg7ff68deja.png) 

23.    Do a double-click on the transform component and set Transforms to customsda.PatientDTL2, after that click OK:


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/um4eqy0akvlo1tprsiij.png) 

24.    Now, you have your Rule definitions ready:


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/jx3ogpzzquhiziirmjq4.png)

25.    Click the Save button and Go to the Interoperability menu:


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/odui4n11nplijeudocnf.png) 

26.    Go to Interoperability > List > Productions:


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/aaj5zk9gz1svhla0cg73.png) 

27.    Select Patients2Production and click the Open button:


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/h9ul7lamlvou9ired0m2.png) 

28.    We will run our new Production! Click the Start button:


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ru16ipkil1o0q64v6jjw.png) 

29.    Select PatentProcess and Go to the Messages tab to see the results (messages):


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/fu23qdu9bp4504ylwzb7.png) 

30.    Click on a message to see a Sequence Diagram with the transformation results:


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/3atilfwkltfdnm5s91c7.png)

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

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