HL7 EDI

Follow the steps below to install an HL7 EDI connector in Anypoint Studio.

To use HL7 EDI with Maven, add the following dependency to your pom.xml file:

The HL7 EDI uses a YAML format called ESL (for EDI Schema Language) to represent EDI schemas. Basic ESLs define the structure of ER7 messages in terms of structures (message structures, in HL7 terminology), groups, segments, composites, and elements. ESLs for the HL7 versions v2.1, v2.2, v2.3.1, v2.3, v2.4, v2.5, v2.5.1, v2.6, 2.7, 2.7.1, 2.8, and 2.8.1 are included.

To configure the HL7 EDI according to your implementation convention, define an overlay schema. An overlay schema is a special form of ESL that allows you to modify a base schema, such as an HL7 2.5.1 ADT_A01 schema, with your specific conventions. (You don’t need an overlay schema if you’re using the structure defined by the standard, but you can use an overlay to tailor the structure to your usage.)

You can also define your own schemas from scratch. See EDI Schema Language Reference for more details.

To specify a schema according to your implementation convention:

Overlay schemas are very similar in structure to a complete schema definition, but instead of providing all the details of the schema structure, they only list changes. Overlay schemas specify how to use implementation conventions with a particular trading partner to extend and customize the standard.

The following example shows the start of a sample overlay schema that modifies the basic HL7 2.5.1 ADT_A01 message structure definition. This sample customizes the PD1 segment and specifies that it is mandatory, so that an error occurs if the segment is not present in a receive or send message.

A structure overlay details modifications to the base schema definition of an HL7 message structure. Most often these modifications take the form of marking segments or groups in the base definition as unused, but any usage or repetition count change is allowed. Here’s the form taken by a structure overlay:

The modifications in this example specify that the PD1 segment and the INSURANCE group are required in each message (usage: M for mandatory), and that the PROCEDURE group is unused (usage: U). With this overlay, errors are reported if the PD1 segment or the INSURANCE group is not present in a message, or if the PROCEDURE group is present.

The key-value pairs at the structure level are:

Each item in the list of structure data components is either a segment reference or a group definition. Both are shown here using a compact YAML syntax where the values for each reference are given as comma-separated key-value pairs enclosed in curly braces. The values are:

The values in a group definition are:

The following is an overlay example that shows how you can add a new segment to an existing structure:

This overlay extends the base v2.6 ORR_O02 message structure to include a PV1 segment in the PATIENT group nested in the RESPONSE group. The after value gives the position of the segment preceding the insertion point.

A segment overlay details modifications to the base schema definition. Most often these modifications take the form of marking elements or composites in the base definition as unused, but any usage or repetition count change is allowed. Here is a full overlay including some sample segment overlays:

This example modifies the base definitions for the ROL and DG1 segments. This example makes the values at position 2 and 4 of the ROL segment optional (they are required in the base definition), and makes all values after the first four in the DG1 segment unused (which drops them from the metadata representation and means they are ignored in data).

Segment modifications only affect structures included in the overlay with explicit references to the modified segments. That’s why the ROL and DG1 segment references need to be included in the structure part of the schema, even though nothing (such as usage or repetition count) is being changed for these segments at the structure level.

The above example uses the compact form for segment modifications that only involve a truncate, while modifications that make changes to individual values are expressed in expanded form. As with all the other YAML examples, the two forms are actually equivalent and can be used interchangeably.

The key-value pairs in a segment overlay are:

The values list references values in the segment by position. The values for these references are:

To use the connector, you need to 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 schema location follows the /hl7/{version}/{message structure}.esl pattern. For example, if you’re using the 2.5.1 version and the ADT_A01 message structure, your schema location is /hl7/v2_5_1/ADT_A01.esl.

If you’re creating a custom implementation convention (whether full schemas, or overlay schemas), you should put your schemas under a directory in src/main/app and refer to the location using ${app.home}. For example, if you’ve put your ADT_A01 schema under src/main/app/mypartner/ADT_A01.esl, your schema location is ${app.home}/mypartner/ADT_A01.esl. Mule Runtime automatically checks src/main/app for any locations that contain the ${app.home} value.

If you configure the connector with multiple message structure schemas (whether in separate schema definitions files, as with the provided schemas, or in a single file), you may need to define a mapping from HL7 event and message types to message structures.

HL7 defines the Message Type in the component values of MSH-09. The HL7 EDI Connector uses these component values to find the structure schema to be used for processing a receive message, according to the following rules:

The Event- and Message-to-Message Structure Map is an optional configuration parameter. The structure map must be a YAML file consisting of a map from each Event Type to a map for each supported Message Type to the actual Message Structure. Here’s a sample of what this looks like:

Each version of HL7 defines a different set of mappings from event type and message type to message structure. The default mappings are provided in the same jar as the standard HL7 schema definitions, in files named event-message.yaml. You use the same type of paths for these mapping definitions as for the actual message structure schemas.

The HL7 connector enables reading or writing of HL7 documents into or from the canonical ER7 message structure. This structure is represented as a hierarchy of Java Maps and Lists, which can be manipulated using DataWeave or code. Each transaction has its own structure, defined in the schemas as previously outlined.

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

Individual messages have their own maps, with keys matching the segments of the message. For instance, an ACK message would use the message structure ID "ACK", and the data for the ACK message sent or received would be present as 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.

There are two special cases where generic handling is used for data not included in a schema definition. The first is for HL7 values of type 'varies'. Since these values may consist of any structure of components and subcomponents, and may be repeated, the parser uses a list of maps representation for each 'varies'. 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. So a simple text value for an OBX-05 Observation Value field, for instance, would just use the key OBX-05 in a map. If there were two components present, these would use keys OBX-05-01 and OBX-05-02.

Extension segments with tags matching a pattern configured under parser options use a similar structure to the 'varies' values, but only within a single map for the entire segment. Repeated values are not supported by the extension segment parsing and writing code.

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:

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

To read an HL7 message, search the palette for "HL7 EDI" and drag the HL7 EDI building block into a flow. Then, go to the properties view, select the connector configuration you previously created and select the Read operation:

This operation reads any byte stream into the structure described by your HL7 schemas.

HL7 EDI validates the message structure when it reads it in. Message validation includes checking the syntax and content of the MSH and all component segments of the message. Normally errors are logged and accumulated, and reported in the generated ACK message provided in the generated data structure. All messages, whether error free or with non-fatal errors are passed on for processing as part of the output message Map. Errors reading the input data cause exceptions to be thrown.

Error data entered in the receive data map uses the HL7Error class, a read-only JavaBean with the following properties:

Error data is returned by the read operation as an optional list with the "Errors" key.

To write an outgoing message, construct an outgoing HL7 EDI message according to the previously defined structure.

For example, this sample creates an outgoing HL7 message that is written to a file.

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

For example:

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 in order to do the send.