HL7 EDI Connector 4.3

Anypoint Connector for HL7 EDI (HL7 EDI Connector) is a collection of features that facilitate integration with healthcare systems by providing the tools needed to easily create, read, and transform HL7 version v2.x messages within Mule. Health Level Seven International (HL7) is a standards development organization that defines a set of standards for the transport and communication of healthcare information.

For compatibility information and fixed issues, see the HL7 EDI Connector Release Notes.

Standard schema definitions are included in HL7 EDI Connector for HL7 versions 2.1, 2.2, 2.3.1, 2.3, 2.4, 2.5, 2.5.1, 2.6, 2.7, 2.7.1, 2.8, 2.8.1. The schemas are provided in two forms:

Standard HL7

Uses required or optional status data types, field lengths, and repetition counts (as listed) for each HL7 version.
Lax HL7

All segments and value items are optional. These low-level data types are treated as simple strings. Field lengths and repetition counts are not enforced.

Both forms of schemas are available in the connector’s classpath. Standard HL7 schemas use the path /hl7/v2_5_1/ADT_A01.esl.
Lax schemas use the path /hl7lax/v2_5_1/ADT_A01.esl.

The schema definitions you need for HL7 supplied schemas are included.

For complete information about schemas, see EDI Schema Language Reference.

Before You Begin

To use this connector, you must be familiar with:

Anypoint Connectors
Mule runtime engine (Mule)
Elements and global elements in a Mule flow
Creating a Mule app using Anypoint Studio or Anypoint Code Builder
HL7 EDI Connector

To use HL7 EDI Connector, you must have:

Purchased a MuleSoft license for HL7. Contact your Account Representative about purchasing a license.
Anypoint Studio or Anypoint Code Builder.

Understanding the EDI Schema Language

HL7 EDI Connector uses a YAML format called EDI Schema Language (ESL) to represent EDI schemas. Basic ESLs define the structure of Electronic Data Interchange (EDI) messages in terms of:

structures (message structures, in HL7 terminology)
groups
segments, composites, and elements

You can customize the HL7 schema definitions to suit your data by copying and editing the schema definitions directly or by using a console tool to generate a simplified schema based on one or more sample documents. Alternatively, you can use an overlay schema for HL7, as with other EDI formats, but this option is not recommended due to the complexity of HL7 definitions.

You can define your own schemas from scratch, or you can copy and edit a base HL7 schema definition to suit your data as shown in the EDI Schema Language Reference.

Finding the HL7 Schema Location

To use the connector, you must know the locations of the schemas in your project. If you’re using the out-of-the-box HL7 schemas and not customizing anything, the standard schema location follows the /hl7/{version}/{message structure}.esl pattern and the lax schema location follows the /hl7lax/{version}/{message structure}.esl pattern.

For example, if you’re using the 2.5.1 schema version and the ADT_A01 message structure, your schema location is /hl7/v2_5_1/ADT_A01.esl for the standard version or /hl7lax/v2_5_1/ADT_A01.esl for the lax version.

If you’re using one or more custom schemas, put these in a directory in src/main/mule and refer to the location using ${app.home}. For example, if you put your ADT_A01 schema under src/main/mule/mypartner/ADT_A01.esl, your schema location is `${app.home}/mypartner/ADT_A01.esl.

The Mule runtime engine automatically checks src/main/mule for any locations that contain the ${app.home} value.

The Hierarchy of X12 EDI Connector Message Structure

Use this connector to read or write HL7 documents into (or from) the canonical ER7 message structure. This structure is a hierarchy of Java Maps and Lists. You use either DataWeave or code to manipulate them. Each transaction structure is defined in the schemas.

The message itself contains the following keys, some of which apply only to either the read operation or the write operation, as indicated:

Key Name Description

Key Name	Description
ACK (read only)	Message generated by the module during the read operation. The `MSA-01` acknowledgment code value is based on the parser configuration settings.
Data (read or write)	Wrapper for message data, with a key matching the message structure ID value that links to the actual data. Allows different messages to be included in the metadata and handled in DataWeave mappings.
Delimiters (read or write)	The delimiters used for the message. The characters in the string of delimiters are interpreted based on their position in string, in the following order: component separator, repetition separator, escape character, and subcomponent separator, with a value of `U` indicating no value in that position.
Errors (read only)	A list of errors associated with the input message.
Id	Message structure ID.
MSH (read only)	Link that receives MSH segment data.
Name (read only)	Message structure name.

ACK (read only)

Message generated by the module during the read operation. The MSA-01 acknowledgment code value is based on the parser configuration settings.

Data (read or write)

Wrapper for message data, with a key matching the message structure ID value that links to the actual data. Allows different messages to be included in the metadata and handled in DataWeave mappings.

Delimiters (read or write)

The delimiters used for the message. The characters in the string of delimiters are interpreted based on their position in string, in the following order: component separator, repetition separator, escape character, and subcomponent separator, with a value of U indicating no value in that position.

Errors (read only)

A list of errors associated with the input message.

Message structure ID.

MSH (read only)

Link that receives MSH segment data.

Name (read only)

Message structure name.

Individual messages have their own maps, with keys matching the segments of the message. For example, an ACK message uses the message structure ID ACK, and the data for the sent or received ACK message is an ACK value in the data map. The ACK message is itself a map, and the segments and groups of the message are represented as maps (in the case of singleton instances) or lists of maps (for repeating instances) with positional keys.

In two special cases, use generic handling for data that is not included in a schema definition.

The first case is HL7 values of the varies type. Because these values consist of any structure of components and subcomponents that can be repeated, the parser uses a list of map representations for each varies of type. The keys in each map are generated as the value is parsed, matching standard HL7 value names with two digits used for each nesting level. For example, a simple text value for an OBX-05 Observation Value field would use the key OBX-05 in a map. If there are two components present, they use keys OBX-05-01 and OBX-05-02.

The second case is when extension segments have tags that match a pattern configured under parser options. These are similar in structure to the varies values, with the exception of only being within a single map for the entire segment.

The maps containing extension segment data are added to the basic message map in lists with the key ExtensionSegs. In addition to the actual extension segment data, the map for the extension segment contains two other keys:

Key Description

Key	Description
Ident	The extension segment identifier (tag).
Position	The position of the segment within the message structure, as a two-digit string. This is the same as the position of the immediately preceding defined segment, as defined in the schema. If a `ZVN` extension segment is used following the `EVN` segment in an `ADT_A01` message structure, the `ZVN` is at position `03)`.

Ident

The extension segment identifier (tag).

Position

The position of the segment within the message structure, as a two-digit string. This is the same as the position of the immediately preceding defined segment, as defined in the schema. If a ZVN extension segment is used following the EVN segment in an ADT_A01 message structure, the ZVN is at position 03).

If extension segments are used in nested groups, the list containing those segments are included in the map representing that group. Extension segments are ordered by position in the lists created by the parser, and must also be ordered by position when writing.

About Sending Acknowledgments

An ACK (acknowledgment) message is an HL7 message that enables you to acknowledge to a message sender that your application has received a message. ACK messages are the same as any other HL7 message write operations, except that you set the ACK message to what was generated during the read operation as the output message under a Data key.

Here is an example:

    <hl7-edi:read config-ref="HL7_EDI__Configuration1" doc:name="HL7 EDI"/>\
    ...
    <dw:transform-message doc:name="Create Outgoing Message">
      <dw:set-payload><![CDATA[%dw 1.0
%output application/java
---
{
  Name: "ACK",
  MSH: payload.ACK.MSH,
  Id: "ACK",
  Data: {
    ACK: payload.ACK
  }
}]]></dw:set-payload>
    </dw:transform-message>
    <hl7-edi:write config-ref="HL7_EDI__Configuration" messageStructure="InMessage" doc:name="ACK"/>
    ...
    <file:outbound-endpoint responseTimeout="10000" doc:name="File" path="output" outputPattern="ack.edi"/>

The generated ACK messages have MSH data set up for sending back to the sender of the original message, so you don’t need to change anything in the data to perform the send.

If you include an ACK message schema in your configuration, that schema is used to both receive and generate ACK messages. If you don’t specify an ACK schema, the standard hl7/v2_5_1/ACK.esl schema default is used.

Exchange Templates and Examples

Anypoint Exchange provides both templates and examples that you can use as starting points for your apps and examples that illustrate a complete solution.

Next Step

After you complete the prerequisites, you are ready to create your own app and configure the connector using Anypoint Studio.