HL7 EDI - Examples - Mule 4
Use the following examples to see how to customize a schema, configure the Message Header (MSH) application and facility identification for you and your trading partner, and view a test flow with an HTTP Listener that initiates a flow.
Simplify a Schema Using Example Messages
The HL7 standard definitions are very complex, with segments often having twenty or more components. Many of these components are broken down into subcomponents. This component nesting can make mapping HL7 difficult, since the DataSense view of the message has to contain all these subcomponents.
In practice, most users of HL7 populate only a small fraction of the total HL7 standard definitions. To take advantage of this, HL7 EDI Connector provides a console-based Java tool you can use to simplify your schema definitions by eliminating components that are not normally used in your messages.
The schema simplification tool is in the
hl7-simplify-4.0.0.jar file, which is found in the standard
MuleSoft enterprise Maven repositories (under group ID com.mulesoft.connectors).
The tool accepts a message structure schema and one or more example messages
(as separate files) as input, and generates an output schema reduced 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 hl7-simplify-4.0.0.jar {input-schema} {output-schema} {sample1} {sample2} ...The placeholders in this syntax represent the following values:
-
input-schemaMessage structure schema used to read the messages, which can be a file or a classpath reference to a supplied schema such as the
/hl7/v2_5_1/ADT_A05.eslpath. -
output-schemaFile path for the simplified schema output.
-
sample1…nFile paths to the sample messages.
Ensure that each sample message file is saved with a carriage return (CR) line ending, which is the required HL7 segment delimiter. Text editors generally use the default line ending for your operating system, and this might 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 }
...Because unused components of a segment cannot be dropped from the segment
definition unless they’re at the end of the segment, the simplification
tool substitutes a varies data type for the component and marks it
with Usage: U for Unused. The repetition count for varies remains the
same as for the original component, but it does not display
in the DataSense view of the data you see in DataWeave.
When the schema simplification tool checks for data present in the messages, it handles each occurrence of a composite in context. Different uses of the same composite might have different values present in your samples. When this happens, the composite is defined more than once, using different identifiers.
The simplified schema retains the segment positions from the original schema. You can delete these position values from the simplified schema, because they’re not used by HL7 EDI Connector unless you use position prefixes on segment keys (one of the connector configuration options).
Example: HL7 Studio
The following flow can be loaded from the XML.
<?xml version="1.0" encoding="UTF-8"?>
<mule xmlns:ee="http://www.mulesoft.org/schema/mule/ee/core"
xmlns:hl7="http://www.mulesoft.org/schema/mule/hl7"
xmlns:http="http://www.mulesoft.org/schema/mule/http"
xmlns="http://www.mulesoft.org/schema/mule/core"
xmlns:doc="http://www.mulesoft.org/schema/mule/documentation"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.mulesoft.org/schema/mule/core
http://www.mulesoft.org/schema/mule/core/current/mule.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/hl7
http://www.mulesoft.org/schema/mule/hl7/current/mule-hl7.xsd
http://www.mulesoft.org/schema/mule/ee/core
http://www.mulesoft.org/schema/mule/ee/core/current/mule-ee.xsd">
<http:listener-config name="HTTP_Listener_config"
doc:name="HTTP Listener config" >
<http:listener-connection host="localhost" port="8081" />
</http:listener-config>
<hl7:config name="HL7_Extension_Config" doc:name="HL7 Extension Config" identKeys="true">
<hl7:schemas >
<hl7:schema value="/hl7/v2_5_1/ADT_A05.esl" />
<hl7:schema value="/hl7/v2_5_1/ADT_A01.esl" />
</hl7:schemas>
</hl7:config>
<flow name="hl7testFlow" >
<http:listener doc:name="Listener" config-ref="HTTP_Listener_config" path="/hl7"/>
<hl7:read doc:name="Read" config-ref="HL7_Extension_Config"/>
<ee:transform doc:name="Transform Message" >
<ee:message >
<ee:set-payload ><![CDATA[%dw 2.0
output application/java
---
{
Delimiters: payload.Delimiters,
Id: payload.Id
}]]></ee:set-payload>
</ee:message>
</ee:transform>
<hl7:write doc:name="Write" config-ref="HL7_Extension_Config"/>
</flow>
</mule>Set Your HL7 Identification in XML
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 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>"
Reading and Validating HL7 ER7 Messages
To read an HL7 message:
-
Search the palette for HL7 EDI and drag it into a flow.
-
From the properties view, select the previously created connector configuration and then the
Readoperation.This operation reads any byte stream into the structure as described by your HL7 schemas.
HL7 EDI validates the message structure when read:
-
Checking the syntax and content of the MSH and all component segments of the message.
-
The generated ACK message logs, accumulates, and reports errors 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.
-
Reading input data errors can throw exceptions.
-
Error data entered in the receive data map uses the HL7Error class, a read-only JavaBean with the following properties:
| Property | Description |
|---|---|
|
Zero-based index within the input of the segment causing the error |
|
Flag for a fatal error, meaning the associated message was rejected as a result of the error |
|
Enumeration for the different types of errors defined by the HL7 standards (ERR-3 values) |
|
Error code, as defined by the HL7 standard for the indicated type of error |
|
Text description of the error |
The Read operation returns error data as an optional list with the Errors key.