HL7 v2 Integration
This page describes HL7v2-IN module which provides API to ingest and process HL7 v2 messages.
Last updated
This page describes HL7v2-IN module which provides API to ingest and process HL7 v2 messages.
Last updated
In 2019, HL7 v2 is still the most widely-used standard for healthcare IT systems integration. If you're developing software which receives information from other systems within a hospital/clinic, most likely it will be HL7 v2 messages.
To process those messages, react on them and modify data stored in your Aidbox, there is a Hl7v2-in module. It provides two resources: Hl7v2Config and Hl7v2Message. Hl7v2Configdetermines how messages will be parsed and processed. Hl7v2Message represents a single received HL7 v2 message and contains raw representation, status (processed/error), error description in case of error and other useful information.
Both Hl7v2Config and Hl7v2Message are managed with standard CRUD API.
Most likely when a new HL7 v2 message is received, you want to make changes in the database — create, update or delete FHIR resources. It's where the Mapper module comes on stage — HL7v2-IN module parses the message and then passes message data to the Mapping resource specified in Hl7v2Config instance via the mapping reference.
Here is an example of a mapping which creates a new Patient resource with a name taken from the PID.5 field each time a new message is received:
Please note that Mapping returns FHIR Transaction Bundle, so it can produce as many CRUD operations as you need. Any other Aidbox operation/endpoint can be triggered as well (for instance, SQL endpoint).
To start ingesting HL7 v2 messages, you need to create Hl7v2Config first:
The isStrict attribute specifies if message parsing will be strict or not. When isStrict is true, HL7 v2 parser will fail on any schema error like missing required field or segment. If isStrict is false, then parser will try to produce AST of the message even when required fields are missing or segment hierarchy is broken. In this case, you have a chance to get null values in your mapping for fields which you don't expect to be null.
Refer to a mapping which will process your messages with the mapping attribute. Please note that you aren't obligated to keep all of your mapping logic inside a single Mapping resource — you can have one as an entrypoint and then dispatch execution to other mappings with the $include directive.
Access the Aidbox UI and navigate to the "HL7 v2" tab in the left menu, then click the "New" button in the top right corner.
Copy-paste a following test message to the "New Message" form:
Pick an Hl7v2Config instance using the radio button and click the "Create" button:
You'll see a newly created message with additional information like status, parsed structure, outcome, etc.:
To submit a new HL7 v2 Message, just create it with the REST API:
Newly created messages should have received status, otherwise they won't be processed.
201 Created response indicates that message was created and processed. Response body will contain additional processing details such as:
status — processed when message was successfully parsed and mapping was applied or error when there was an error/exception in one of those steps;
parsed — structured representation of the message;
outcome — Transaction Bundle returned by the mapping or error information if the status is error.
You can try to submit malformed message (truncated) to see what the result will be:
Usually HL7 messages are transmitted using the MLLP protocol. To convert a MLLP traffic to HTTP requests, there is an open-source hl7proxy utility provided by Health Samurai. It's available on GitHub and there are pre-compiled binaries for major operating systems and architectures.
Follow the hl7proxy's README for installation and usage instructions.
Most likely you'll want to authenticate hl7proxy requests with basic auth using Aidbox's Client resource. Also it's a good idea to forbid everything except for POSTing new Hl7Messages. You can do both things by submitting the following Bundle. It will create a Client resource and AccessPolicy for it.
To authorize hl7proxy requests, one needs to pass an Authorization header with every request to Aidbox. You can provide a value for this header with the -header command-line flag:
To calculate a value for the Authorization header, you need to do base64encode(clientId + ":" clientSecret). You can do it in bash:
Replace xxxxxxxxxx in the command above with a string returned by this command.
Once hl7proxy is up and running, you can use HAPI TestPanel to send sample HL7 v2 messages. Make sure that TestPanel doesn't report any errors on message delivery. hl7proxy output should contain information about every received message and log lineSent to Aidbox: 201 Created indicates a successful delivery.
You can define custom segment using Hl7v2Config resource.
msh - message structure code
segment - custom segment name
Each field:
name - HL7v2 field name
key - key under which parsed value is stored
type - HL7v2 field type
