HL7 v2 Integration

Video version of this tutorial
Introduction
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.
Mapper module
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:
1
PUT /Mapping/test
2
Content-Type: text/yaml
3
​
4
resourceType: Mapping
5
id: test
6
body:
7
  resourceType: Bundle
8
  type: transaction
9
  entry:
10
    - resource:
11
        resourceType: Patient
12
        name:
13
          - given: ["$ msg.PID.name.0.given"]
14
            family: "$ msg.PID.name.0.family.surname"
15
      request:
16
        method: POST
17
        url: "/fhir/Patient"
Copied!
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).
Creating a Hl7v2Config Resource
To start ingesting HL7 v2 messages, you need to create Hl7v2Config first:
1
PUT /Hl7v2Config/default
2
Content-Type: text/yaml
3
​
4
resourceType: Hl7v2Config
5
id: default
6
isStrict: false
7
mapping:
8
  resourceType: Mapping
9
  id: test
Copied!
Strict and Non-strict Parsing
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.
Mapping Entrypoint
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.
Submitting a Message with Aidbox UI
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:
1
MSH|^~\&|AccMgr|1|||20151015200643||ADT^A01|599102|P|2.3|foo||
2
EVN|A01|20151010045502|||||
3
PID|1|010107111^^^MS4^PN^|1609220^^^MS4^MR^001|1609220^^^MS4^MR^001|BARRETT^JEAN^SANDY^^||19420923|F||C|STRAWBERRY AVE^FOUR OAKS LODGE^NEWTOWN^CA^99774^USA^^||(111)222-3333||ENG|W|CHR|111155555550^^^MS4001^AN^001|123-22-1111||||OKLAHOMA|||||||N
4
PV1|1|I|PREOP^101^1^1^^^S|3|||37^JOHN^SMITH^Q^^^^^^AccMgr^^^^CI|||01||||1|||37^JOHN^SMITH^Q^^^^^^AccMgr^^^^CI|2|40007716^^^AccMgr^VN|4|||||||||||||||||||1||G|||20050110045253||||||
5
GT1|1|010107127^^^MS4^PN^|BARRETT^JEAN^S^^|BARRETT^LAWRENCE^E^^|1212 BLUEBERRY ST^SIX PINES LODGE^OLDTOWN^CA^99112^USA^|(818)111-1111||19311120|F||A|111-22-3333||||RETIRED|^^^^00000^|||||||20120815|||||0000007496|W||||||||Y|||CHR||||||||RETIRED||||||C
6
IN1|1|0423|UNICARE IP|^^^^     |||||||19931107|||MCR|BARRETT^JEAN^S^^|A|19321712|1212 BLUEBERRY ST^SIX PINES LODGE^OLDTOWN^CA^99112^USA^^^|||1||||||||||||||1234567890|||||||F|^^^^00000^|N||||123456789
7
IN2||123456789|0000005555^RETIRED|||358888999A||||||||||||||||||||||||||||||Y|||CHR||||W|||RETIRED|||||||||||||||||(818)111-2222||||||||C
8
IN1|2|0423|2304|OMNICARE OPP|PO BOX 15033^PO BOX 15033^PARSINGTON^NY^30222|||087770999400099|RETIRED|||20120808|||COM|BARRETT^JEAN^S^^|A|19321210|1212 BLUEBERRY ST^SIX PINES LODGE^OLDTOWN^CA^99112^USA^^^|||2||||||||||||||899991666|||||||F|^^^^00000^|N||||010105555
9
IN2||353333833|0000003333^RETIRED|||||||||||||||||||||||||||||||||Y|||CHR||||W|||RETIRED|||||||||||||||||(818)333-3333||||||||C
Copied!
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.:
Submitting a Message with the REST API
To submit a new HL7 v2 Message, just create it with the REST API:
1
POST /Hl7v2Message
2
Content-Type: text/yaml
3
​
4
resourceType: Hl7v2Message
5
src: |-
6
  MSH|^~\&|AccMgr|1|||20151015200643||ADT^A01|599102|P|2.3|foo||
7
  EVN|A01|20151010045502|||||
8
  PID|1|010107111^^^MS4^PN^|1609220^^^MS4^MR^001|1609220^^^MS4^MR^001|BARRETT^JEAN^SANDY^^||19420923|F||C|STRAWBERRY AVE^FOUR OAKS LODGE^NEWTOWN^CA^99774^USA^^||(111)222-3333||ENG|W|CHR|111155555550^^^MS4001^AN^001|123-22-1111||||OKLAHOMA|||||||N
9
  PV1|1|I|PREOP^101^1^1^^^S|3|||37^JOHN^SMITH^Q^^^^^^AccMgr^^^^CI|||01||||1|||37^JOHN^SMITH^Q^^^^^^AccMgr^^^^CI|2|40007716^^^AccMgr^VN|4|||||||||||||||||||1||G|||20050110045253||||||
10
  GT1|1|010107127^^^MS4^PN^|BARRETT^JEAN^S^^|BARRETT^LAWRENCE^E^^|1212 BLUEBERRY ST^SIX PINES LODGE^OLDTOWN^CA^99112^USA^|(818)111-1111||19311120|F||A|111-22-3333||||RETIRED|^^^^00000^|||||||20120815|||||0000007496|W||||||||Y|||CHR||||||||RETIRED||||||C
11
  IN1|1|0423|UNICARE IP|^^^^     |||||||19931107|||MCR|BARRETT^JEAN^S^^|A|19321712|1212 BLUEBERRY ST^SIX PINES LODGE^OLDTOWN^CA^99112^USA^^^|||1||||||||||||||1234567890|||||||F|^^^^00000^|N||||123456789
12
  IN2||123456789|0000005555^RETIRED|||358888999A||||||||||||||||||||||||||||||Y|||CHR||||W|||RETIRED|||||||||||||||||(818)111-2222||||||||C
13
  IN1|2|0423|2304|OMNICARE OPP|PO BOX 15033^PO BOX 15033^PARSINGTON^NY^30222|||087770999400099|RETIRED|||20120808|||COM|BARRETT^JEAN^S^^|A|19321210|1212 BLUEBERRY ST^SIX PINES LODGE^OLDTOWN^CA^99112^USA^^^|||2||||||||||||||899991666|||||||F|^^^^00000^|N||||010105555
14
  IN2||353333833|0000003333^RETIRED|||||||||||||||||||||||||||||||||Y|||CHR||||W|||RETIRED|||||||||||||||||(818)333-3333||||||||C
15
status: received
16
config:
17
  resourceType: Hl7v2Config
18
  id: default
Copied!
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:
1
POST /Hl7v2Message
2
Content-Type: text/yaml
3
​
4
resourceType: Hl7v2Message
5
src: |-
6
  MSH|^~
7
status: received
8
config:
9
  resourceType: Hl7v2Config
10
  id: default
Copied!
Capturing a MLLP Traffic
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.
1
POST /
2
Content-Type: text/yaml
3
​
4
resourceType: Bundle
5
type: transaction
6
entry:
7
  - resource:
8
      resourceType: Client
9
      id: hl7proxy
10
      grant_types: ["basic"]
11
      secret: <PUT SECRET STRING HERE>
12
    request:
13
      url: /Client/hl7proxy
14
      method: PUT
15
  - resource:
16
      resourceType: AccessPolicy
17
      id: allow-hl7proxy-to-create-hl7v2message
18
      link:
19
        - id: hl7proxy
20
          resourceType: Client
21
      engine: json-schema
22
      schema:
23
        type: object
24
        required: ["uri", "request-method"]
25
        properties:
26
          uri:
27
            const: "/Hl7v2Message"
28
          request-method:
29
            const: post
30
    request:
31
      url: /AccessPolicy/allow-hl7proxy-to-create-hl7v2message
32
      method: PUT
Copied!
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:
1
./hl7proxy -port 5000 -config default -url https://your-box.edge.aidbox.app/ -header "Authorization: Basic xxxxxxxxxxxxx"
Copied!
To calculate a value for the Authorization header, you need to do base64encode(clientId + ":" clientSecret). You can do it in bash:
1
echo -n "hl7proxy:<PUT SECRET STRING HERE>" | base64
Copied!
Replace xxxxxxxxxx in the command above with a string returned by this command.
Using HAPI TestPanel to send messages with MLLP
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.
User-defined segments (Z-segments)
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
Example
1
mapping:
2
  id: example
3
  resourceType: Mapping
4
isStrict: false
5
extensions:
6
  - msh: ADT_A01
7
    fields:
8
      - key: id
9
        name: ID
10
        type: EI
11
      - key: startDate
12
        name: START_DATE
13
        type: TS
14
      - key: endDate
15
        name: END_DATE
16
        type: TS
17
      - key: state
18
        name: STATE
19
        type: ST
20
      - key: value
21
        name: VALUE
22
        type: ST
23
    segment: ZBE
24
id: cfg-1
25
resourceType: Hl7v2Config
Copied!

Export logs to Datadog tutorial

Next - Modules

FHIR Resources

Last modified 1mo ago

Copy link

Contents

Introduction

Mapper module

Creating a Hl7v2Config Resource

Submitting a Message with Aidbox UI

Submitting a Message with the REST API

Capturing a MLLP Traffic

Using HAPI TestPanel to send messages with MLLP

User-defined segments (Z-segments)

Example