--- schema_version: "1" id: 724b84ccf10de388cbabda6f2cc08184c1d168a45a210a7ea59754dc70dd90a4 title: HL7 EDI - Customizing Schemas and Mapping Message Types collection: mulesoft version: current locale: en-us portal_url: https://docs.salesforce.com/mulesoft/current/en-us/hl7-connector/latest/hl7-connector-config-topics.md canonical_url: https://docs.mulesoft.com/hl7-connector/latest/hl7-connector-config-topics source_site: docs.mulesoft.com content_type: documentation content_hash: 08971c228ff0108be864080832ad0eef56c9407be52983c6bd82cd88d0879b04 description: MuleSoft Documentation Site release: "5.0" latest: true --- --- product: HL7 EDI Connector version: 5.0 is-latest-version: true --- # HL7 EDI - Customizing Schemas and Mapping Message Types > For the full documentation index, see: https://docs.mulesoft.com/llms.txt 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](https://docs.mulesoft.com/x12-edi-connector/latest/x12-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: ```yaml 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: ```yaml 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 `` element for each document type: ```xml hl7/v2_6/ADT_A01.esl ``` 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: ```yaml 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: ```text 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: ```text 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 ValueStudio 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

enforceERRSegmentRepeatability="true"

Enforces the ERR Segment repeatability (count) in the acknowledgment.

## Next Step After you complete connector configuration, you can try the [Examples](https://docs.mulesoft.com/hl7-connector/latest/hl7-connector-examples). ## See Also - [Introduction to Anypoint Connectors](https://docs.mulesoft.com/connectors/introduction/introduction-to-anypoint-connectors) - [Salesforce Help](https://help.salesforce.com)