ks-fhir-gen

Description

This is a proposal for a solution described in HL7 test message generator (DPI-I-464) InterSystems Community opportunity idea.

This proof of concept application converts FHIR (Fast Healthcare Interoperability Resources) resources generated by Synthea into HL7 v2 messages.

Synthea, an open-source synthetic patient generator, produces realistic healthcare data in FHIR format. It generates a set of resource bundles containing varied FHIR vR4 resources : Patient, Observation, Encounter, etc.

The application processes these FHIR resources and transforms them into HL7 v2 messages using DTL data transformations.

A number of helper functions are available to the transformations to map FHIR values and concepts to HL7 v2 equivalents. FHIR code system URLS are mapped to simpler code system names using a lookup table (LUT).

Usage

Prerequisites

Make sure you have git and Docker desktop installed.

Installation

Clone/git pull the repo into any local directory.

Use the ‘recurse-submodules’ option to clone latest synthea version, or leave it out and copy your own customized version into the ‘synthea’ folder

$ git clone --recurse-submodules https://github.com/theanor/ks-fhir-gen.git

Open the terminal in this directory and call the command to build and run InterSystems IRIS in container:
Note: Users running containers on a Linux CLI, should use “docker compose” instead of “docker-compose”
See Install the Compose plugin

$ docker-compose up -d

To open IRIS Terminal do:

$ docker-compose exec iris iris session iris -U IRISAPP
IRISAPP>

Or use vscode action to open a terminal.

Launch ZPM and run the unit tests

IRISAPP>zpm "test ks-fhir-gen -v"

To exit the terminal, do any of the following:

Enter HALT or H (not case-sensitive)

The Synthea based HL7 v2 messages generator

The Synthea generator is implemented by a business service class ks.fhir.dtl.vr4.bs.SyntheaGeneratorService.

The service inbound adapter is responsible for generating FHIR resources and pass them to the service OnProcessInput() method.

Resources can be grouped in batches forming a logical group (e.g. resources pertaining to same patient). The adapter signals the end of the current batch by calling the OnProcessInput() method passing a $$$NULLOREF.

The service uses business rules to select a transformation for each generated resource, and use to generate an HL7 v2 message that is sent to configured target config names.

The tests include a sample generator interoperability production.

The production is using a very basic set of rules and DTL transforms to generate HL7 v2 messages :

• ADT^A01 and ADT^A04 from Encounter resources
• ORU^R01 from Observation resources

The service sends HL7 v2 messages to an operation that output them in the ./test/runtime/HL7/Out directory

Each batch is sent in a separate session.

SyntheaGeneratorService settings

PatientCount : the number of patients in a batch

BatchCount : the number of batches to generate. The adapter will stop generating resources after generating this number of batches.

SyntheaHome : Synthea home directory

SyntheaOutputDirectory : Synthea output directory. The adapter will delete files in this directory after each batch generation.

TargetConfigNames : target config names for the generated HL7 v2 messages

TransformRule : business rule class

CallInterval : interval between batches (seconds)

Customizing the generator

How the service is using the rules

The business rule in the TransformRule setting drives the transformation of generated resources into messages sent to targets in the interoperability production.

Rules are evaluated using the service as context object. The service exposes the following transient properties that can be used to select the appropriate transformation class :

• Resource : the instance of the resource (extends HS.FHIR.DTL.vR4.Model.Base.Resource)
• Transform : the selected transform class

If the rule set returns 1 (true), the selected Transform will be used and the resulting message will be sent to targets.

If the rule set returns 0 (false), the resource is ignored.

Creating transforms

The service calls the selected transform passing the resource as source object and expecting the resulting message as target object. It also passes an object extending the ks.fhir.dtl.vr4.ReferenceResolverInterface as auxilliary parameter “aux”

This aux object implements

Method ResolveReference(reference As HS.FHIR.DTL.vR4.Model.Base.Reference, Output sc As %Status) As HS.FHIR.DTL.vR4.Model.Base.Resource 

Using other FHIR data sources

To use another source than synthetic random data generated by Synthea :

• implement an inbound adapter obtaining resources
• extend AbstractGeneratorService to process them

In this repository

Sample FHIR data

test\resource\fhir

Code system LUT

resource\lut\MFHIRHL7.xml

HL7 output of the test production

test\runtime\HL7\Out

.vscode folder

Contains two files to setup vscode environment:

.vscode/settings.json

Settings file to let you immediately code in VSCode with VSCode ObjectScript plugin)

.vscode/launch.json

Config file if you want to debug with VSCode ObjectScript

src folder

Contains source files.
src/iris contains InterSystems IRIS Objectscript code

tests folder

Contains unit tests for the ObjectScript classes

dev.md

Contains a set of useful commands that will help during the development

docker-compose.yml

A docker engine helper file to manage images building and rule ports mapping an the host to container folders(volumes) mapping

Dockerfile

The simplest dockerfile which starts IRIS and imports code from /src folder into it.
Use the related docker-compose.yml to easily setup additional parametes like port number and where you map keys and host folders.

iris.script

Contains objectscript commands that are feeded to iris during the image building

module.xml

IPM Module’s description of the code in the repository.
It describes what is loaded with the method, how it is being tested and what apps neeed to be created, what files need to be copied.

Read about all the files in this artilce

Troubleshooting

If you have issues with docker image building here are some recipes that could help.

1. You are out of free space in docker. You can expand the amount of space or clean up maually via docker desktop. Or you can call the following line to clean up:

docker system prune -f

2. We use multi-stage image building which in some cases doesn’t work. Switch the target to builder from final in the docker compose and try again.