Contact Us 1-800-596-4880
  1. Homepage
  2. Healthcare Toolkit (3.1)

  3. HL7 EDI

HL7 EDI Connector

HL7 EDI lets you convert HL7 ER7 messages to and from DataWeave-compatible representations using lists and maps.

HL7 EDI includes:

  • HL7 ER7 message-reading, message-validation, and message-writing

  • Integration with DataSense and DataWeave

  • HL7 message packs for 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.

  • The ability to define your own schemas or customize the base HL7 schemas

Prerequisites

This document assumes you have, a working knowledge with HL7. See the Release Notes for compatibility information.

To use the HL7 EDI connector in a production environment, you must have purchased a MuleSoft license for Anypoint B2B.

Using the HL7 EDI Connector

  1. Install the HL7 EDI Connector.

  2. Create Schemas to describe messages for your implementation.

  3. Configure HL7 EDI for your trading partner according to your implementation convention.

  4. Use HL7 EDI inside Mule flows.

To Install this Connector

  1. In Anypoint Studio (Studio), click the Exchange icon in the Studio taskbar.

  2. Click Login in Anypoint Exchange.

  3. Search for the HL7 connector and click Install.

  4. Follow the prompts to install the connector.

  5. Repeat steps 3 and 4 to install the HL7 MLLP connector.

When Studio has an update, a message displays in the lower right corner, which you can click to install the update.

If you are coding a Mavenized Mule application, include this XML snippet in your pom.xml file.

<dependency>
 <groupId>org.mule.module</groupId>
 <artifactId>mule-module-hl7</artifactId>
 <version>3.1.0</version>
</dependency>

Inside the <version> tags, enter the HL7 connector version number, or use the word RELEASE for the latest release or SNAPSHOT for the latest available version.

Create Schemas

Create schemas to describe your messages according to your implementation.

EDI Schema Language

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, in two different forms:

  • Standard HL7, using required or optional status, data types, field lengths, and repetition counts as listed for each HL7 version.

  • Lax HL7, where all segments and value items are optional, all low-level data types are treated as simple strings, and field lengths and repetition counts are not enforced.

You can customize the HL7 schema definitions to suit your own 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. It is also possible to 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 also define your own schemas from scratch. See the EDI Schema Language Reference for more details.

YAML uses a combination of lists and sets of key-value pairs. The order of values is not important, as long as the required items are present. Quotes (either single or double quotes) are used around values which may consist of digits but are meant to be interpreted as strings (since otherwise the YAML parser treats the values as numbers). Indentation is used to show the nesting of lists.

For readability, the ESL structures shown here define all simple key-value pairs before any lists that are part of the same definition.

Copying and Editing Schema Definitions

HL7 schema definitions are distributed inside the edi-schemas-hl7-1.3.0.jar. You can copy a message structure schema from this JAR and edit it to match your specific needs. If you only need to make changes at the segment level you can just copy the message structure schema; if you need to change segment definitions you must also copy the basedefs.esl schema of the same version, since that file contains the segment, composite, and element definitions.

The EDI Schema Language Reference gives an overview of the ESL schema structure used by all the EDI connectors, including the HL7 EDI Connector. You should consult that for background on the structure of the schema definitions.

Here’s a sample HL7 message structure schema, for the standard v2.5.1 ADT_A05 message structure:

form: HL7
version: '2.5.1'
imports: [ '/hl7/v2_5_1/basedefs.esl' ]
id: 'ADT_A05'
name: 'ADT_A05'
data:
- { idRef: 'MSH', position: '01', usage: M }
- { idRef: 'SFT', position: '02', usage: O, count: '>1' }
- { idRef: 'EVN', position: '03', usage: M }
- { idRef: 'PID', position: '04', usage: M }
- { idRef: 'PD1', position: '05', usage: O }
- { idRef: 'ROL', position: '06', usage: O, count: '>1' }
- { idRef: 'NK1', position: '07', usage: O, count: '>1' }
- { idRef: 'PV1', position: '08', usage: M }
- { idRef: 'PV2', position: '09', usage: O }
- { idRef: 'ROL', position: '10', usage: O, count: '>1' }
- { idRef: 'DB1', position: '11', usage: O, count: '>1' }
- { idRef: 'OBX', position: '12', usage: O, count: '>1' }
- { idRef: 'AL1', position: '13', usage: O, count: '>1' }
- { idRef: 'DG1', position: '14', usage: O, count: '>1' }
- { idRef: 'DRG', position: '15', usage: O }
- groupId: 'PROCEDURE'
  count: '>1'
  usage: O
  items:
  - { idRef: 'PR1', position: '17', usage: M }
  - { idRef: 'ROL', position: '18', usage: O, count: '>1' }
- { idRef: 'GT1', position: '20', usage: O, count: '>1' }
- groupId: 'INSURANCE'
  count: '>1'
  usage: O
  items:
  - { idRef: 'IN1', position: '22', usage: M }
  - { idRef: 'IN2', position: '23', usage: O }
  - { idRef: 'IN3', position: '24', usage: O, count: '>1' }
  - { idRef: 'ROL', position: '25', usage: O, count: '>1' }
- { idRef: 'ACC', position: '27', usage: O }
- { idRef: 'UB1', position: '28', usage: O }
- { idRef: 'UB2', position: '29', usage: O }

This shows the list of segments making up the ADT_A05 message structure, including the segment groups PROCEDURE and INSURANCE. Since the above is the standard definition (not the lax version), it includes mandatory segments (indicated with usage: M) as well as optional segments (indicated with usage: O). The full set of usage codes used for HL7 are:

  • C for Conditional (equivalent to Optional)

  • M for Mandatory

  • O for Optional

  • U for Unused (accepted without warning when reading, but not present in the data passed on from the read; ignored when writing)

The possible number of occurrences of a segment or group is given by the count value. This defaults to a value of 1,

If you just want to delete some segments from the message structure, or change some segment requirements from mandatory to optional (or vice versa), you can easily make the change in your copy of the schema and use the modified version in your application.

You can also add segments that are not present in the original message structure definition. For this, it is best if you first remove the position values from all the existing segment and group definition lines in the schema, otherwise, you must renumber everything following an added segment. If you remove the explicit position numbers, segments and groups are assigned position numbers sequentially, and for most purposes, these numbers are not seen by HL7 EDI Connector 3.1.0 applications.

If you want to add a standard HL7 segment to a message structure, you just reference it with an idRef line at the appropriate place, and HL7 obtains the definition from the basedefs.esl file referenced as an import.

The following partial example shows CON segments added to an ADT_A05 message structure:

form: HL7
version: '2.5.1'
imports: [ '/hl7/v2_5_1/basedefs.esl' ]
id: 'ADT_A05'
name: 'ADT_A05'
data:
- { idRef: 'MSH', usage: M }
- { idRef: 'SFT', usage: O, count: '>1' }
- { idRef: 'EVN', usage: M }
- { idRef: 'PID', usage: M }
- { idRef: 'PD1', usage: O }
- { idRef: 'CON', usage: O, count: '>1' }
- { idRef: 'NTE', usage: O }
- { idRef: 'ROL', usage: O, count: '>1' }
- { idRef: 'NK1', usage: O, count: '>1' }
- { idRef: 'PV1', usage: M }
- { idRef: 'PV2', usage: O }
- { idRef: 'CON', usage: O, count: '>1' }
- { idRef: 'ROL', usage: O, count: '>1' }
  ...

If you want to define a non-standard segment for your message structure, add the segment definition to the schema. This is more complex than just modifying the segment structure, since you need to list all components in the segment. The easiest starting point for this is to find a similar standard HL7 segment and copy the definition used for that standard segment from the basedefs.esl file. You can then add the segments key following your message structure definition, followed by one or more segment definitions.

See the following section for an example of a schema combining a message structure and segment definitions.

Simplifying a Schema Using Example Messages

The HL7 standard definitions are very complex, with segments often having twenty or more components and many of the components composites which themselves are broken down into many subcomponents. This can make mapping HL7 difficult, since the DataSense view of the message has to contain all these subcomponents.

In practice, most users of HL7 only populate a small fraction of the total HL7 standard definitions. To take advantage of this, the HL7 EDI Connector provides a console-based Java tool you can use to simplify your schema definitions by eliminating components which are not normally used in your messages.

The schema simplification tool is distributed as the edi-schemas-hl7-1.3.0-simplify.jar (see the See Also section of this document for the link). It takes a message structure schema, and one or more example messages (as separate files) as input, and generates an output schema reduced down to only those segments and components present in one or more of the sample messages.

To use this tool, download the jar and open a command line console, then type:

java -jar edi-schemas-hl7-1.3.0-simplify.jar {input-schema} {output-schema} {sample1} {sample2} ...

Where:

  • input-schema is the message structure schema used to read the messages, which can be a file or a classpath reference to a supplied schema such as /hl7/v2_5_1/ADT_A05.esl.

  • output-schema is the file path for the simplified schema output.

  • sample1…​n are the file paths to the sample messages.

Make sure the sample message files are saved with carriage return (CR) line endings, since this is the required HL7 segment delimiter. Text editors generally use the default line ending for your operating system, which may not be correct.

Here’s a partial example of a simplified schema generated using this tool:

form: HL7
version: '2.5.1'
structures:
- id: 'SIU_S12'
  name: 'SIU_S12'
  data:
  - { idRef: 'MSH', position: '01', usage: O }
  - { idRef: 'SCH', position: '02', usage: O }
  - groupId: 'PATIENT'
    count: '>1'
    usage: O
    items:
    - { idRef: 'PID', position: '06', usage: O }
    - { idRef: 'PV1', position: '08', usage: O }
  - groupId: 'RESOURCES'
    count: '>1'
    usage: O
    items:
    - { idRef: 'RGS', position: '14', usage: O }
    - groupId: 'SERVICE'
      count: '>1'
      usage: O
      items:
      - { idRef: 'AIS', position: '16', usage: O }
    - groupId: 'GENERAL_RESOURCE'
      count: '>1'
      usage: O
      items:
      - { idRef: 'AIG', position: '20', usage: O }
    - groupId: 'LOCATION_RESOURCE'
      count: '>1'
      usage: O
      items:
      - { idRef: 'AIL', position: '24', usage: O }
    - groupId: 'PERSONNEL_RESOURCE'
      count: '>1'
      usage: O
      items:
      - { idRef: 'AIP', position: '28', usage: O }
segments:
- id: 'AIG'
  name: 'Appointment Information - General Resource'
  varTag: 'AIG'
  values:
  - { idRef: 'SI', name: 'Set ID - AIG', usage: O }
  - { idRef: 'varies', name: 'Segment Action Code', usage: U, count: '>1' }
  - { idRef: 'CE_2', name: 'Resource ID', usage: O }
  - { idRef: 'varies', name: 'Resource Type', usage: U, count: '>1' }
  - { idRef: 'varies', name: 'Resource Group', usage: U, count: '>1' }
  - { idRef: 'varies', name: 'Resource Quantity', usage: U, count: '>1' }
  - { idRef: 'varies', name: 'Resource Quantity Units', usage: U, count: '>1' }
  - { idRef: 'TS', name: 'Start Date/Time', usage: O }
- id: 'AIL'
  name: 'Appointment Information - Location Resource'
  varTag: 'AIL'
  values:
  - { idRef: 'SI', name: 'Set ID - AIL', usage: O }
  - { idRef: 'varies', name: 'Segment Action Code', usage: U, count: '>1' }
  - { idRef: 'PL', name: 'Location Resource ID', usage: O, count: '>1' }
  - { idRef: 'CE', name: 'Location Type-AIL', usage: O }
  - { idRef: 'varies', name: 'Location Group', usage: U, count: '>1' }
  - { idRef: 'TS', name: 'Start Date/Time', usage: O }
- id: 'AIP'
  name: 'Appointment Information - Personnel Resource'
  varTag: 'AIP'
  values:
  - { idRef: 'SI', name: 'Set ID - AIP', usage: O }
  - { idRef: 'varies', name: 'Segment Action Code', usage: U, count: '>1' }
  - { idRef: 'XCN_2', name: 'Personnel Resource ID', usage: O, count: '>1' }
  - { idRef: 'CE_1', name: 'Resource Type', usage: O }
  - { idRef: 'varies', name: 'Resource Group', usage: U, count: '>1' }
  - { idRef: 'TS', name: 'Start Date/Time', usage: O }
  ...
composites:
- id: 'CE'
  name: 'Coded Element'
  values:
  - { idRef: 'ST', name: 'Identifier', usage: O }
  - { idRef: 'ST', name: 'Text', usage: O }
- id: 'CE_1'
  name: 'Coded Element'
  values:
  - { idRef: 'ST', name: 'Identifier', usage: O }
- id: 'CE_2'
  name: 'Coded Element'
  values:
  - { idRef: 'ST', name: 'Identifier', usage: O }
  - { idRef: 'ST', name: 'Text', usage: O }
  - { idRef: 'ID', name: 'Name of Coding System', usage: O }
  ...

Unused components of a segment cannot just be dropped from the segment definition (unless they’re at the end of the segment), so the simplification tool just substitutes a "varies" data type for the component and marks it with Usage: U for Unused. The repetition count for the "varies" remains the same as for the original component in this case, but it will not show up in the DataSense view of the data you see in Data Weave.

When the schema simplification tool checks which data is present in the messages, it handles each occurrence of a composite in context, so different usages of the same composite may have different values present. When this happens, the composite is defined more than once with different identifiers. The CE composite in the above example shows this.

The simplified schema retains the segment postions from the original schema. You can delete these position values from the simplified schema if you want, since they’re not used by the HL7 EDI Connector unless you use position prefixes on segment keys (one of the connector configuration options).

Determining the HL7 Schema Location

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 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 version and the ADT_A01 message structure, your schema location is /hl7/v2_5_1/ADT_A01.esl for the standard version (including required values, data types, and lengths/repeat counts) or /hl7lax/v2_5_1/ADT_A01.esl for the lax version.

If you’re using one or more custom schemas, you should put these 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.

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

Event and Message to Message Structure Map

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 the 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:

  • If the MSH-09-01 Message Type value is ACK, always use the predefined ACK schema.

  • Otherwise, if the MSH-09-03 Message Structure value is present (a value such as ADT_A01), use the schema structure with that ID.

  • Otherwise, use a configured Event and Message to Message Structure Map to determine the message structure from the specified Event Type (MSH-09-02) and Message Type (MSH-09-01) values.

The Event and Message to Message Structure Map is an optional configuration parameter. It 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:

A01: { ADT: ADT_A01, ACK: ACK }
A02: { ADT: ADT_A02, ACK: ACK }
A03: { ADT: ADT_A03, ACK: ACK }
A04: { ADT: ADT_A01, ACK: ACK }
A05: { ADT: ADT_A05, ACK: ACK }
A06: { ADT: ADT_A06, ACK: ACK }
A07: { ADT: ADT_A06, ACK: ACK }
A08: { ADT: ADT_A01, ACK: ACK }

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.

Configure HL7 EDI Using the Studio Visual Editor

After you install the connector and configure your schema customizations (if any), you can start using the connector. Create separate configurations for each implementation convention.

  1. Click the Global Elements tab at the base of the canvas, and click Create.

  2. In the Choose Global Type wizard, use the filter to locate and select HL7 EDI: Configuration, and click OK.

  3. Configure the parameters according to the connector reference.

  4. Click OK to save the global connector configurations.

  5. Return to the Message Flow tab in Studio.

General Options

In the general options you can configure settings which apply to both reading and writing HL7 messages:

  • HL7 character encoding, always used for writing messages and used when reading messages unless a different encoding is specified by MSH-18 (Character Set)

  • Disable numeric prefixes for data keys - this option is true by default, which turns off numeric prefixes for segment data; the only reason to turn this option off is for compatibility with mappings defined for the HL7 EDI Connector 3.0.0.

  • Manually create or edit the list of schemas.

Set Your HL7 Identification in the Studio Visual Editor

You can configure the Message Header (MSH) application and facility identification for you and your trading partner on the HL7 EDI connector configuration.

The values you set are used when writing HL7 messages to supply the namespace ID, universal ID, and universal ID type, and are verified in receive messages. If you don’t want to restrict incoming messages you can leave these blank, and set the values for outgoing messages on the write operation or the actual outgoing message. Values set on the write operation override the connector configuration, and values set directly on the message override both the connector configuration and any values set on the write operation.

In Studio, these values are set in Global Element Properties.

  • Self identification parameters identify your side of the trading partner relationship.

    Self identification settings:

    Mule Application Namespace ID (MSH-3-1/MSH-5-1)
Mule Application Universal ID (MSH-3-2/MSH-5-2)
Mule Application Universal ID Type (MSH-3-3/MSH-5-3)

  • Partner identification parameters identify your trading partner.

    Partner identification settings:

    Partner Application Namespace ID (MSH-3-1/MSH-5-1}
Partner Application Universal ID (MSH-3-2/MSH-5-2}
Partner Application Universal ID Type (MSH-3-3/MSH-5-3)

Setting Parser Options

You can set the following options if needed:

  • Validate HL7 Message Version

  • Event and message to message structure map path (required if using multiple message structures, unless the MSH-09-03 message structure value is always present in received messages)

  • Required processing ID (to specify a particular processing ID required on receive messages, such as P for Production)

  • Pattern for generic extension segment names (to allow handling of extension segments as maps of field values)

  • Fail when value length outside allowed range

  • Fail when invalid character in value

  • Fail when too many repeats of value

  • Fail when unknown segment in message

  • Fail when segment out of order in message set

  • Fail when unused segment included in message set

  • Fail when too many repeats of segment

Setting Delimiter Characters

You can set the delimiter characters used when writing messages, if you wish to modify the defaults.

Configure HL7 EDI Using the Studio XML Editor or Standalone

After you install the connector and configure your schema customizations (if any), you can start using the connector. Create separate configurations for each implementation convention.

  1. Ensure that you have included the EDI namespaces in your configuration file.

    <mule xmlns:tracking="http://www.mulesoft.org/schema/mule/ee/tracking"
  xmlns:tcp="http://www.mulesoft.org/schema/mule/tcp"
  xmlns:dw="http://www.mulesoft.org/schema/mule/ee/dw"
  xmlns:http="http://www.mulesoft.org/schema/mule/http"
  xmlns:hl7-edi="http://www.mulesoft.org/schema/mule/hl7-edi"
  xmlns="http://www.mulesoft.org/schema/mule/core"
  xmlns:doc="http://www.mulesoft.org/schema/mule/documentation"
  xmlns:spring="http://www.springframework.org/schema/beans"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.mulesoft.org/schema/mule/tcp
    http://www.mulesoft.org/schema/mule/tcp/current/mule-tcp.xsd
    http://www.springframework.org/schema/beans
    http://www.springframework.org/schema/beans/spring-beans-current.xsd
    http://www.mulesoft.org/schema/mule/core
    http://www.mulesoft.org/schema/mule/core/current/mule.xsd
    http://www.mulesoft.org/schema/mule/hl7-edi
    http://www.mulesoft.org/schema/mule/hl7-edi/current/mule-hl7-edi.xsd
    http://www.mulesoft.org/schema/mule/http
    http://www.mulesoft.org/schema/mule/http/current/mule-http.xsd
    http://www.mulesoft.org/schema/mule/ee/dw
    http://www.mulesoft.org/schema/mule/ee/dw/current/dw.xsd
    http://www.mulesoft.org/schema/mule/ee/tracking
    http://www.mulesoft.org/schema/mule/ee/tracking/current/mule-tracking-ee.xsd">

  2. Configure HL7 EDI in your application by creating a global configuration outside and above your flows using the following global configuration code:

      <hl7-edi:config name="HL7_EDI__Configuration" identKeys="true" doc:name="HL7 EDI: Configuration">
    <hl7-edi:schemas>
      <hl7-edi:schema>hl7/v2_6/ADT_A01.esl</hl7-edi:schema>
    </hl7-edi:schemas>
  </hl7-edi:config>

Setting Your HL7 Identification in XML

You can configure the Message Header (MSH) application and facility identification for you and your trading partner on the HL7 EDI connector configuration.

The values you set are used when writing HL7 messages to supply the namespace ID, universal ID, and universal ID type, and are verified in receive messages. If you don’t want to restrict incoming messages you can leave these blank, and set the values for outgoing messages on the write operation or the actual outgoing message. Values set on the write operation override the connector configuration, and values set directly on the message override both the connector configuration and any values set on the write operation.

  • Self identification parameters identify your side of the trading partner relationship.

    Self identification parameters:

    appNamespaceIdSelf="<value>"
appUniversalIdSelf="<value>"
appUniversalIdTypeSelf="<value>"

  • Partner identification parameters identify your trading partner.

    Partner identification parameters:

    appNamespaceIdPartner="<value>"
appUniversalIdPartner="<value>"
appUniversalIdTypePartner="<value>"

Setting Parser Options

You can set the following options if needed:

XML Value Studio Option

validateHL7Version="true"

Validate HL7 Message Version

eventMessageMap="/hl7/v2_5_1/event-message.yaml"

Event and message to message structure map path (required if using multiple message structures, unless the MSH-09-03 message structure value is always present in received messages)

processingId="PRODUCTION"

Required processing ID (to specify a particular processing ID required on receive messages, such as P for Production)

genericExtensionPattern="Z.."

Java regular pattern for generic extension segment names (to allow handling of extension segments as maps of field values)

valueLengthErrorFail="true"

Fail when the length of a value falls outside the allowed range

invalidCharacterInValueFail="true"

Fail when a value contains an invalid character

wrongValuesRepeatsFail="true"

Fail when a value is repeated too many times

unknownSegmentFail="true"

Fail when an unknown segment is in a message

segmentOutOfOrderFail="true"

Fail when a segment is out of order in message set

unusedSegmentPresentFail="true"

Fail when an unused segment is included in a message set

wrongSegmentsRepeatsFail="true"

Fail when a segment is repeated too many times

Setting Your Schema Locations

You can only configure schema locations in the Studio XML view.

In Studio, switch to the XML view by clicking Configuration XML and modify your HL7 EDI configuration to include a list of all the schemas you wish to include by adding an <http://edischema[edi:schema]> element for each document type:

  <hl7-edi:config name="HL7_EDI__Configuration" identKeys="true" doc:name="HL7 EDI: Configuration">
    <hl7-edi:schemas>
      <hl7-edi:schema>hl7/v2_6/ADT_A01.esl</hl7-edi:schema>
    </hl7-edi:schemas>
  </hl7-edi:config>

After you create a global element for your HL7 EDI, configure the message structure, operations, and acknowledgments.

Use HL7 EDI Inside Mule Flows

Use the HL7 EDI connector in your flows for reading and writing messages, and sending acknowledgments.

Understanding the HL7 Message Structure

The HL7 connector reads and writes HL7 documents into or from a 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 which is defined in the schemas.

The HL7 message contains the following keys:

Key name Description

ACK (read only)

ACK message generated in response to the input data. The MSA-1 acknowledgment code value is based on the parser configuration settings. To send an acknowledgment, see the Sending Acknowledgments section below.

Data (read or write)

Wrapper for message data with a key matching the message structure ID value linking to the actual data. This allows different messages to be included in the metadata and handled in DataWeave mappings.

Delimiters (read only)

The delimiters used for the message. The characters in the string are interpreted based on position in the following order: (component separator), (repetition separator), (escape character), (subcomponent separator).

Errors (read only)

A list of errors which are associated with the input message. See the HL7Error structure description in the Reading and Validating HL7 Messages section below.

Id

Message structure ID.

MSH (read only)

Link to received MSH segment data.

Name (read only)

Message structure name.

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 the varies type. 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 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. 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 are two components present, they 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:

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).

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.

Reading and Validating HL7 ER7 Messages

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.

Read Operations

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:

Property Description

segment

The zero-based index within the input of the segment causing the error.

fatal

Flag for a fatal error, meaning the associated message was rejected as a result of the error.

errorType

Enumeration for the different types of errors defined by the HL7 standards (ERR-3 values).

errorCode

Error code, as defined by the HL7 standard for the indicated type of error.

errorText

Text description of the error.

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

Writing HL7 EDI Messages

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.

  ...
<hl7-edi:write config-ref="HealthCare" doc:name="Send ACK"/>
<file:outbound-endpoint responseTimeout="10000" doc:name="File" path="output" outputPattern="ack.edi"/>

Sending Acknowledgments

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:

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

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

Default ACK message structure

HL7 DataWeave Examples

The following example shows the use of HL7 and DataWeave to read a message received over HTTP and send the acknowledgment back as the response.

Read and send acknowledgment flow 
<?xml version="1.0" encoding="UTF-8"?>

<mule xmlns:tracking="http://www.mulesoft.org/schema/mule/ee/tracking"
  xmlns:tcp="http://www.mulesoft.org/schema/mule/tcp"
  xmlns:dw="http://www.mulesoft.org/schema/mule/ee/dw"
  xmlns:http="http://www.mulesoft.org/schema/mule/http"
  xmlns:hl7-edi="http://www.mulesoft.org/schema/mule/hl7-edi"
  xmlns="http://www.mulesoft.org/schema/mule/core"
  xmlns:doc="http://www.mulesoft.org/schema/mule/documentation"
  xmlns:spring="http://www.springframework.org/schema/beans"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.mulesoft.org/schema/mule/tcp
    http://www.mulesoft.org/schema/mule/tcp/current/mule-tcp.xsd
    http://www.springframework.org/schema/beans
    http://www.springframework.org/schema/beans/spring-beans-current.xsd
    http://www.mulesoft.org/schema/mule/core
    http://www.mulesoft.org/schema/mule/core/current/mule.xsd
    http://www.mulesoft.org/schema/mule/hl7-edi
    http://www.mulesoft.org/schema/mule/hl7-edi/current/mule-hl7-edi.xsd
    http://www.mulesoft.org/schema/mule/http
    http://www.mulesoft.org/schema/mule/http/current/mule-http.xsd
    http://www.mulesoft.org/schema/mule/ee/dw
    http://www.mulesoft.org/schema/mule/ee/dw/current/dw.xsd
    http://www.mulesoft.org/schema/mule/ee/tracking
    http://www.mulesoft.org/schema/mule/ee/tracking/current/mule-tracking-ee.xsd">
  <http:listener-config name="HTTP_Listener_Configuration" host="0.0.0.0" port="8080" doc:name="HTTP Listener Configuration"/>
  <hl7-edi:config name="HL7_EDI__Configuration" identKeys="true" doc:name="HL7 EDI: Configuration">
    <hl7-edi:schemas>
      <hl7-edi:schema>hl7/v2_6/ADT_A01.esl</hl7-edi:schema>
    </hl7-edi:schemas>
  </hl7-edi:config>
  <flow name="Acknowledgment">
    <http:listener config-ref="HTTP_Listener_Configuration" path="/ack" allowedMethods="POST" doc:name="HTTP"/>
    <hl7-edi:read config-ref="HL7_EDI__Configuration" doc:name="HL7 EDI"/>
    <dw:transform-message doc:name="Transform 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="HL7 EDI"/>
    <logger message="#[payload]" level="INFO" doc:name="Logger"/>
  </flow>
</mule>

The example below shows how you can extract particular values from a receive message in DataWeave (using a simplified schema for the message, which eliminates many unused fields).

Extract values from receive message 
<?xml version="1.0" encoding="UTF-8"?>

<mule xmlns:jersey="http://www.mulesoft.org/schema/mule/jersey"
  xmlns:metadata="http://www.mulesoft.org/schema/mule/metadata"
  xmlns:dw="http://www.mulesoft.org/schema/mule/ee/dw"
  xmlns:http="http://www.mulesoft.org/schema/mule/http"
  xmlns:hl7-edi="http://www.mulesoft.org/schema/mule/hl7-edi"
  xmlns="http://www.mulesoft.org/schema/mule/core"
  xmlns:doc="http://www.mulesoft.org/schema/mule/documentation"
  xmlns:spring="http://www.springframework.org/schema/beans"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.springframework.org/schema/beans
    http://www.springframework.org/schema/beans/spring-beans-current.xsd
    http://www.mulesoft.org/schema/mule/core
    http://www.mulesoft.org/schema/mule/core/current/mule.xsd
    http://www.mulesoft.org/schema/mule/hl7-edi
    http://www.mulesoft.org/schema/mule/hl7-edi/current/mule-hl7-edi.xsd
    http://www.mulesoft.org/schema/mule/http
    http://www.mulesoft.org/schema/mule/http/current/mule-http.xsd
    http://www.mulesoft.org/schema/mule/ee/dw
    http://www.mulesoft.org/schema/mule/ee/dw/current/dw.xsd
    http://www.mulesoft.org/schema/mule/jersey
    http://www.mulesoft.org/schema/mule/jersey/current/mule-jersey.xsd">
    <http:listener-config name="HTTP_Listener_Configuration" host="0.0.0.0" port="8081" doc:name="HTTP Listener Configuration"/>
    <hl7-edi:config name="HL7_EDI_Configuration" doc:name="HL7 EDI: Configuration" identKeys="true">
        <hl7-edi:schemas>
            <hl7-edi:schema>schemas/SIU_S12-simplified.esl</hl7-edi:schema>
        </hl7-edi:schemas>
    </hl7-edi:config>
    <flow name="hl7-demoFlow">
        <http:listener config-ref="HTTP_Listener_Configuration" path="/json" doc:name="HTTP"/>
        <hl7-edi:read config-ref="HL7_EDI_Configuration" doc:name="HL7 EDI"/>
        <dw:transform-message doc:name="Transform Message" metadata:id="6f9793a8-8007-4b02-bdbc-802d64ce5d83">
            <dw:set-payload><![CDATA[%dw 1.0
%output application/json
---
{
  id: payload.Data.SIU_S12.PATIENT[0].PID.PID-02-01,
  firstName: payload.Data.SIU_S12.PATIENT[0].PID.PID-05[0].PID-05-02,
  lastName: payload.Data.SIU_S12.PATIENT[0].PID.PID-05[0].PID-05-01-01
}]]></dw:set-payload>
        </dw:transform-message>
    </flow>
</mule>

Upgrading From HL7 2.x.x to 3.0.0

In the HL7 v3.0 connector, the sections that follow list components that have been removed from the connector.

HL7 Message Component

The creation of a message can be done by generating a HL7 Message through DataWeave and then invoking the connector’s write operation.

The following flow outputs the MSH|^~\&|TestSendingSystem|MCM||^12399| message.

  <flow name="CreateMessage">
    <http:listener config-ref="HTTP_Listener_Configuration" path="/create" doc:name="HTTP"/>
    <dw:transform-message doc:name="Transform Message">
      <dw:set-payload><![CDATA[%dw 1.0
%output application/java
---
{
  Delimiters: "|^~\&",
  Id: "ADT_A02",
  Data: {
    ADT_A02: {
      "MSH": {
        MSH-03-01: "TestSendingSystem",
        MSH-04-01: "SendingApp",
        MSH-05-01: "SendingFacility",
        MSH-07-01: now,
        MSH-09-01: "ADT",
        MSH-09-02: "A01",
        MSH-09-03: "ADT_A01"
      }
    }
  }
}
]]></dw:set-payload>
    </dw:transform-message>
    <hl7-edi:write config-ref="HL7_EDI__Configuration" messageStructure="InMessage" doc:name="HL7 EDI"/>
  </flow>

HL7 ACK

The HL7 ACK functionality is contained in the connector. The ACK message is automatically generated by the connector when it performs a read operation. See the Sending Acknowledgments section of this document.

HL7 Append Segment

The Append Segment component can be replaced using DataWeave to manipulate the Data object in the HL7 Message structure obtained after a read operation.

The following example adds AL1|2|10001|^Penicillin||Produces hives to the incoming message.

MSH|^~\&|ADT1|MCM|LABADT|MCM|19900607|SECURITY|ADT^A01|MSG00001|P|2.3.1|
EVN|A01|19900607
PID|1||PATID1234^5^M11^ADT1^MR^MCM~123456789^^^USSSA^SS||JONES^WILLIAM^A^III||19610615|M||C|1200 N ELM STREET^^GREENSBORO^NC^27401-1020|GL|(91-9)379-1212|(919)271-3434||S||PATID12345001^2^M10^ADT1^AN^A|123456789|987654^NC|
NK1|1|||||||
PV1|1|I|2000^2012^01||||004777^LEBAUER^SIDNEY^J.|||SUR||||ADM|A0|
AL1|1||^Cat dander|Respiratory distress
  <flow name="AppendSegment">
    <http:listener config-ref="HTTP_Listener_Configuration" path="/append" allowedMethods="POST" doc:name="HTTP"/>
    <hl7-edi:read config-ref="HL7_EDI__Configuration" doc:name="HL7 EDI"/>
    <dw:transform-message doc:name="Transform Message">
      <dw:set-payload><![CDATA[%dw 1.0
%output application/java
---
{
Delimiters: payload.Delimiters,
Id: payload.Id,
Name: payload.Name,
ACK: payload.ACK,
MSH: payload.MSH,
Errors: payload.Errors map ((error , indexOfError) -> {
errorCode: error.errorCode,
errorText: error.errorText,
errorType: error.errorType,
fatal: error.fatal,
segment: error.segment
}),
Data: {
ADT_A01: {
  MSH: payload.Data.ADT_A01.MSH,
  EVN: payload.Data.ADT_A01.EVN,
  PID: payload.Data.ADT_A01.PID,
  NK1: payload.Data.ADT_A01.NK1,
  PV1: payload.Data.ADT_A01.PV1,
  AL1: (payload.Data.ADT_A01.AL1 +
    {
      AL1-01: 2,
      AL1-02-01:"10001",
      AL1-03-02:"Penicillin",
      AL1-05:["Produces hives"]
    })
}
}
}]]></dw:set-payload>
    </dw:transform-message>
    <hl7-edi:write config-ref="HL7_EDI__Configuration" messageStructure="InMessage" doc:name="Write_HL7"/>
    <logger message="#[payload]" level="INFO" doc:name="Logger"/>
  </flow>

HL7 Delete Segment

HL7 2.0.x Delete Segment component allows the user to delete a segment specifying the segment ID. The deletion operation can involve the complete segment or just the last segment repetition.

The following code blocks illustrate how this component can be replaced with DataWeave, the flows operate over this incoming message:

MSH|^~\&|ADT1|MCM|LABADT|MCM|19900607|SECURITY|ADT^A01|MSG00001|P|2.3.1|
EVN|A01|19900607
PID|1||PATID1234^5^M11^ADT1^MR^MCM~123456789^^^USSSA^SS||JONES^WILLIAM^A^III||19610615|M||C|1200 N ELM STREET^^GREENSBORO^NC^27401-1020|GL|(91-9)379-1212|(919)271-3434||S||PATID12345001^2^M10^ADT1^AN^A|123456789|987654^NC|
NK1|1|||||||
PV1|1|I|2000^2012^01||||004777^LEBAUER^SIDNEY^J.|||SUR||||ADM|A0|
AL1|1||^Cat dander|Respiratory distress
AL1|2||^Penicillin||Produces hives|
  <flow name="RemoveSegment">
    <http:listener config-ref="HTTP_Listener_Configuration" path="/removeSegment" allowedMethods="POST" doc:name="HTTP"/>
    <hl7-edi:read config-ref="HL7_EDI__Configuration" doc:name="HL7 EDI"/>
    <dw:transform-message doc:name="Transform Message">
      <dw:set-payload><![CDATA[%dw 1.0
%output application/java
%var emptySegment = []
---
{
  Delimiters: payload.Delimiters,
  Id: payload.Id,
  Name: payload.Name,
  ACK: payload.ACK,
  MSH: payload.MSH,
  Errors: payload.Errors map ((error , indexOfError) -> {
    errorCode: error.errorCode,
    errorText: error.errorText,
    errorType: error.errorType,
    fatal: error.fatal,
    segment: error.segment
  }),
  Data: {
    ADT_A01: {
      MSH: payload.Data.ADT_A01.MSH,
      EVN: payload.Data.ADT_A01.EVN,
      PID: payload.Data.ADT_A01.PID,
      NK1: payload.Data.ADT_A01.NK1,
      PV1: payload.Data.ADT_A01.PV1,
      AL1: emptySegment
    }
  }
}]]></dw:set-payload>
    </dw:transform-message>
    <hl7-edi:write config-ref="HL7_EDI__Configuration" messageStructure="InMessage" doc:name="_HL7 EDI"/>
    <logger message="#[payload]" level="INFO" doc:name="Logger"/>
  </flow>

HL7 Remove Repetition

  <flow name="RemoveRepetition">
    <http:listener config-ref="HTTP_Listener_Configuration" path="/removeRepetition" allowedMethods="POST" doc:name="HTTP"/>
    <hl7-edi:read config-ref="HL7_EDI__Configuration" doc:name="HL7 EDI"/>
    <dw:transform-message doc:name="Transform Message">
      <dw:set-payload><![CDATA[%dw 1.0
%output application/java
%var start = 0
%var end = (sizeOf payload.Data.ADT_A01.AL1) -2
%var updatedSegment = payload.Data.ADT_A01.AL1[start[0] .. end[0]]
---
{
  Delimiters: payload.Delimiters,
  Id: payload.Id,
  Name: payload.Name,
  ACK: payload.ACK,
  MSH: payload.MSH,
  Errors: payload.Errors map ((error , indexOfError) -> {
    errorCode: error.errorCode,
    errorText: error.errorText,
    errorType: error.errorType,
    fatal: error.fatal,
    segment: error.segment
  }),
  Data: {
    ADT_A01: {
      MSH: payload.Data.ADT_A01.MSH,
      EVN: payload.Data.ADT_A01.EVN,
      PID: payload.Data.ADT_A01.PID,
      NK1: payload.Data.ADT_A01.NK1,
      PV1: payload.Data.ADT_A01.PV1,
      AL1: updatedSegment
    }
  }
}]]></dw:set-payload>
    </dw:transform-message>
    <hl7-edi:write config-ref="HL7_EDI__Configuration" messageStructure="InMessage" doc:name="Copy_of_HL7 EDI"/>
    <logger message="#[payload]" level="INFO" doc:name="Logger"/>
  </flow>

HL7 Exception Strategy

The exception strategy substitution is up to the user, in the new connector Errors are included in the HL7 Message structure.

The configuration set in the Parser Options of the HL7 EDI Configuration defines when a message is reported to be rejected in the generated ACK.

HL7 Profile Validator Filter

The Validator Filter component can be replaced using the connector to read the message and then verifying that the ERRORS list in the HL7 Message structure is empty.

HL7 Encoding Transformer

This feature is no longer supported by the connector. The encoding transformation can be achieved with DataWeave.

See Also