Contact Us 1-800-596-4880
  1. Homepage
  2. HL7 EDI Connector (4.3)

  3. HL7 EDI Connector Additional Configuration Information

All Connectors

HL7 EDI - Customizing Schemas and Mapping Message Types

Use these options to:

  • Customize your schema definitions

  • Define a mapping from the HL7 event and message types to message structures

  • Customize global elements

Copy and Edit Schema Definitions

HL7 schema definitions are located in the hl7-schemas-4.0.0.jar file, embedded inside the HL7 EDI Connector update site, and within the standard MuleSoft enterprise Maven repositories (under group ID com.mulesoft.connectors). You can copy a message structure schema from the hl7-schemas-4.0.0.jar file and edit it to match your specific needs.

To make changes at the segment level, copy the message structure schema. To change segment definitions, copy the basedefs.esl schema of the same version, as that file contains the segment, composite, and element definitions.

The EDI Schema Language Reference provides an overview of the ESL schema structure used by all the EDI connectors, including HL7 EDI Connector.

The following is an example 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 that compose the ADT_A05 message structure, including the segment groups PROCEDURE and INSURANCE. Because this example illustrates the standard definition (not the lax version), it includes both mandatory segments (indicated with usage: M) and optional segments (indicated with usage: O). The full set of usage codes used for HL7 includes:

  • 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 operation and ignored when writing

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

To delete segments from the message structure or change segment requirements from mandatory to optional (or vice versa), make the change in your copy of the schema and use the modified version in your application.

You can add segments that are not present in the original message structure definition. Remove the position values from all 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 applications.

If you want to add a standard HL7 segment to a message structure, 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 nonstandard segment for your message structure, add the segment definition to the schema. This is more complex than just modifying the segment structure, because you need to list all components in the segment. The easiest starting point 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 segment’s key, following your message structure definition, followed by one or more segment definitions.

Set Your Schema Locations

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

  1. Select the XML view by clicking Configuration XML.

  2. Modify your HL7 EDI configuration to include a list of all the schemas 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>

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

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 must 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, a composite structure of type MSG. HL7 EDI Connector uses these component values to find the structure schema to use for processing a receive message, according to the following rules:

  • If the MSG-01 Message Code value is ACK, always use the predefined ACK schema.

  • If the MSG-03 Message Structure value is present (a value such as ADT_A01), use the schema structure with that ID.

  • If neither of these, then use a configured Event and Message-to-Message Structure Map to determine the message structure from the specified Trigger Event (MSG-02) and Message Code (MSG-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 Code to the actual Message Structure.

Here’s an example:

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

Each version of HL7 defines a different set of mappings from the event type and message code to the message structure. The default mappings are provided in the same JAR file 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.

Uses for the General Tab

Use the General tab to configure settings for 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 the 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 set this option as false is to achieve compatibility with mappings defined for HL7 EDI Connector 3.0.0.

  • Manually create or edit the list of schemas

Set Your HL7 Identification in the Visual Editor

You can configure the Message Header (MSH) application and facility identification for you and your trading partner in 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, then 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 the following Global Element Properties:

  • Self identification parameters identify your side of the trading partner relationship. These are some self identification settings:

    Mule Application Namespace ID (MSH-03/HD-01 when sending, MSH-05/HD-01 when receiving)
Mule Application Universal ID (MSH-03/HD-02 when sending, MSH-05/HD-02 when receiving)
Mule Application Universal ID Type (MSH-03/HD-03 when sending, MSH-05/HD-03 when receiving)

  • Partner identification parameters identify your trading partner. These are some partner identification settings:

    Partner Application Namespace ID (MSH-03/HD-01 when receiving, MSH-05/HD-01 when sending)
Partner Application Universal ID (MSH-03/HD-02 when receiving, MSH-05/HD-02 when sending)
Partner Application Universal ID Type (MSH-03/HD-03 when receiving, MSH-05/HD-03 when sending)

Parser Tab

You can set the following options if needed:

XML Value Studio Option

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 and MSG-03 message structure values are always present in the received messages)

genericExtensionPattern="Z.."

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

invalidCharacterInValueFail="true"

Fail when an invalid character is in a value

missingRequiredValueFail="true"

Fail when a required value is missing

processingId="PRODUCTION"

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

segmentOutOfOrderFail="true"

Fail when a segment is out of order in a message

unknownSegmentFail="true"

Fail when an unknown segment is in a message

unusedSegmentPresentFail="true"

Fail when an unused segment is included in a message

validateHL7Version="true"

Validate the HL7 message version

valueLengthErrorFail="true"

Fail when a value length is outside an allowed range

wrongSegmentsRepeatsFail="true"

Fail when there are too many repeats of a segment

wrongValuesRepeatsFail="true"

Fail when there are too many repetitions of a value

Next Step

After you complete connector configuration, you can try the Examples.

See Also

Back to top