test

Sun Adapter for TCP/IP HL7 User's Guide

Sun Adapter for TCP/IP HL7 Overview

The following topics provide information about HL7 and the TCP/IP HL7 Adapter:

About Sun Adapter for TCP/IP HL7

The Sun Adapter for TCP/IP HL7 is a component of the Sun Java Composite Application Suite (Java CAPS) that enables the Java CAPS ESB system to exchange data with an external TCP/IP application using the HL7 data protocol. The Sun Java CAPS ESB with the TCP/IP HL7 Adapter provides:

TCP/IP HL7 Features

The TCP/IP HL7 Adapter includes the following features:

TCP/IP HL7 Adapter Components

The TCP/IP HL7 Adapter incorporates three components:

The TCP/IP HL7 Message Library, also known as an Object Type Definition (OTD) Library, enables the creation of HL7 interfaces capable of running over TCP/IP, and also utilizes the common Adapter services available in Java CAPS. The TCP/IP HL7 Adapter works hand in hand with the Sun Java CAPS HL7 Message Libraries, versions 2.1 through 2.5.1.

The TCP/IP HL7 Adapter properties allow the user to easily configure the operation of the TCP/IP HL7 Adapter. The Adapter includes a set of properties that are configured in the Connectivity Map and only apply to that Adapter in the Project. It also includes a set of properties that are configured in the Environment and apply to all TCP/IP HL7 Adapters in the Project. These properties are adopted into the Message Library’s functions.

The Message Library handles all of the lower-layer protocol. The Message Library’s behavior is customized using the Adapter configuration properties. These Adapter properties are used by the resource adapter, but are also accessed and used by the prebuilt Collaborations.

About HL7

HL7 is a standard for exchanging information between medical applications and is an abbreviation of Health Level Seven. Level Seven refers to the seventh OSI layer protocol for the health environment. HL7 defines the format and the content of the messages that applications must use when exchanging data with each other under various circumstances.

Hospitals and other medical institutions typically use many different types of systems to communicate with one another. Everything, from patient records to billing information, is tracked and recorded in computer systems. In order for these different types of systems to communicate with each other, they use a standard like HL7.

Note –

In the computer world, a protocol is a formal, well-defined standard for exchanging information between computer applications.

An important part of the HL7 standard is the ACKnowledgment protocol, also known as an ACK. Every time an application accepts a message and consumes the data, it is expected to send an ACKnowledgment message back to the sending application. The sending application is expected to keep on sending a message until it has received an ACK message.

The TCP/IP HL7 Adapter Architecture

The TCP/IP HL7 Adapter's functionality comes from a combination of the TCP/IP HL7 Resource Adapter (RA), the predefined inbound and outbound HL7 Collaborations, and the generic HL7 Message Libraries.

TCP/IP HL7 Resource Adapter

The TCP/IP HL7 Resource Adapter communicates with external HL7 systems, establishes and maintains the TCP/IP socket, manages message enveloping, maintains the sequence numbering file, and provides the HL7 protocol state to the Collaboration. The RA (Resource Adapter) is configured from the Adapter Properties Editor.

HL7 Collaborations

The inbound and outbound HL7 Collaborations provide message validation, sequence numbering, ACK and NAK generation, and recourse actions. The predefined HL7 Collaborations are designed to implement the HL7 standard protocol and inter-operate with similar standard compliant systems by simply changing the Adapter property configuration.

If a system does not conform to the HL7 specification, the Collaborations can be modified for that transaction by changing the Java code using the Collaboration Editor. The Collaborations Java code is designed to be available and “transparent” so you can easily reference the predefined Java code to see how it currently handles HL7 transactions and make the appropriate modifications.

The Collaboration Editor allows you to create and edit Java code to modify a Collaboration for your specific needs. In many cases this code can be created graphically (drag and drop), using the Collaboration Editor’s Business Rules Designer. If you need to change the code of a prebuilt Collaboration, you should duplicate the Collaboration first and then modify it.

The Collaborations are designed to target one unit of work at a time, meaning the resolution of one message at a time. Once the current message transaction is resolved, the Collaboration is free to process the next HL7 message. The general form of the Collaborations is a state machine. Based on the state of the connection, the Collaboration performs the appropriate action. Additional Collaborations can be added to a Project to increase message flow.

Generic HL7 Message Libraries

The generic HL7 Message Libraries are version-agnostic structures used to send and receive HL7 messages, acknowledgements, and negative acknowledgements (NAKs). They provide the Collaboration with only the essential fields for implementing the HL7 protocol. If you need to perform functions that are specific to a version or message type, you can add the appropriate Message Library to the Collaboration.

Sun Java Composite Application Suite Functionality

The TCP/IP HL7 Adapter takes advantage of the Java CAPS facilities to provide journaling and error messaging, as well as monitoring, alerting, and logging. journaling and error messages are sent to JMS queues, which allow flexibility for postprocessing. For example, invalid messages and their negative acknowledgements (NAKs) are sent to a JMS queue. This JMS queue can then be set up to allow the invalid HL7 messages to be viewed, corrected, and resubmitted automatically to the same Adapter.

Modes and Roles

The TCP/IP HL7 Adapter can operate in two modes: standard and delayed ACK. Standard mode is the typical message exchange in HL7 where an HL7 message is sent and an HL7 ACK is received, or the other way around. In delayed ACK mode, the exchange of a message requires two acknowledgements: one to confirm the message was received and the other from the external system that actually received the message to verify that it was received.

In these two modes, the Adapter and the ESB have a number of roles they play within certain scenarios; that is, certain components can fulfill different responsibilities within a protocol. For example, the outbound Collaboration can fulfill two roles in the delayed ACK mode: one as the “sender of messages” that expects two delayed ACKS, and another as the “forwarder of ACKS” from the external system.

Note –

Delayed ACK mode is deprecated as of HL7 version 2.2 and was removed from the HL7 standard as of version 2.5.

Standard Mode

In standard mode, the HL7 Adapter can assume two roles, sender and receiver. These are implemented in the outbound and inbound Collaborations respectively.

HL7 Adapter Sender Role

The outbound Collaboration is the implementation of the Sender and the RA is configured for an outbound data flow. A Java CAPS Service forwards the data to the Adapter, which in turn forwards the data to the accepting HL7 external system. The External System responds with an ACK or NAK response.

HL7 Adapter Receiver Role

The inbound Collaboration is the implementation of the Receiver role in conjunction with the RA being configured for inbound direction. The Adapter accepts a message from the sending HL7 external system, forwards the data to a Java CAPS Service, and responds to the sending system with an ACK or a NAK response.

Delayed ACK Mode

Delayed ACK mode is an extension to the basic HL7 message exchange mode, where there is some middleware component between the Sender and the Receiver. The sending system expects to receive the ACK from the receiving system in addition to the middleware component. In this mode, the ESB can assume two roles in the protocol: as the Sender and as the Receiver.

ESB Sender Role

In this role, the ESB acts as the Sender in the exchange. The HL7 RA is configured for the outbound direction, and the HL7 outbound Collaboration is configured so the Sends App Ack property is set to True. This parameter is used even though the ESB technically does not send an application ACK. Rather, it receives the application ACK and provides the compliment behavior to the ACK sent by the inbound configured Adapter. The two are related in the protocol.

The purpose of this role is for the ESB to act as if it is a system that requires the Delayed ACKs so that it can communicate with a system that operates in the Delayed ACK Receiver role. An example implementation of this role is available in the HL7Outbound sample Project.

ESB Receiver and Forwarder Role

To perform this role, the ESB is configured with two instances of the HL7 Adapter , each performing its own role as Receiver or Forwarder.

Note –

For Delayed ACK, the Receiver and Forwarder must be on the same integration server.

The following steps convey the steps taken in this scenario.

  1. The Receiver accepts the HL7 message. It then returns the first ACK, with an MSH - 5, value “D” (for the Delayed ACK), to the Sender.

  2. The Receiver sends the message to the Forwarder.

  3. The Forwarder sends the message to the receiving External System.

  4. The receiving External System sends an ACK to the Forwarder.

  5. The Forwarder receives the ACK from the External and forwards it on to the Receiver.

  6. The Receiver then forwards the ACK, with an MSH - 5, value “F” indicating that it is the receiving External System’s ACK, to the Sender.

In the Receiver role, the HL7 RA is configured for inbound, and the inbound Collaboration is used with the parameter Sends App Ack set to true. In the Forwarder role, the RA is set to outbound, the parameter Forward External Acks to eGate, is set to true, and the outbound Collaboration is selected.

This configuration table presents the necessary parameters used to configure the Adapter to assume the Delayed ACK roles

Table 1 Adapter Delayed ACK Configuration

Role 

Direction 

Sends App Ack Property 

Forward External Acks 

Sender 

Out 

True 

N/A 

Receiver 

In 

True 

N/A 

Forwarder 

Out 

N/A 

True 

An example of the receiver role is provided in the prjHL7Inbound sample Project. The prjHL7Outbound Project provides a sample implementation of the Forwarder role.

Inbound Functionality

The inbound TCP/IP HL7 Adapter Project, prjHL7Inbound, provides a sample implementation of an inbound flow using the Adapter. It can be configured for standard inbound mode or for forward message mode.

Inbound Adapter Data Flow

The inbound TCP/IP HL7 Adapter Project receives HL7 messages from an external system, sends an acknowledgement of the message to the external, provides sequence numbering, writes the HL7 message to a JMS data queue, and also writes the HL7 message and ACK to a JMS journal queue. Any error messages and NAKs are sent to a JMS error queue.

The HL7 data is processed so all the fields in the MSH segment of the message are stored in an internal structure to generate an HL7 response. Non-HL7 data, including HL7 acknowledgments, automatically generate warnings in the Adapter’s log file and send an HL7 NAK to the external system.

Standard Inbound Message Mode Data Flow and Architecture

    The following steps describe the flow of data for an inbound Adapter:

  1. The external system sends the HL7 message to the Adapter.

  2. The Collaboration receives the HL7 message.

  3. The Collaboration validates the message (if validate is enabled). If it fails, the Collaboration takes the configured recourse action. If the recourse action is stripped and the maximum number of retries has been exceeded, the message and error are written to the error queue.

  4. The Collaboration writes the message to the data queue.

  5. The Collaboration then creates the appropriate ACK and sends it to the RA.

  6. The RA envelopes the ACK and sends it to the External System.

  7. If journaling is enabled, the message and its ACK are written to the journal queue.

Inbound Receiver Message Mode

The Inbound Receiver Message mode is used when the Delayed ACK is configured to fulfill the role of the Receiver in the Delayed ACK scenario. It accepts the message and acknowledges the External and then forwards the message to the component fulfilling the Forwarder role. It then accepts the ACK from the Forwarder and passes it on to the External that sent the message.

    The following steps describe the Inbound Forward Message Role:

  1. The Sender External, sends an HL7 message to the Inbound Adapter, which is configured as a Receiver (Sends App Acks is enabled).

  2. The Inbound Adapter receives the HL7 message and returns the first Acknowledgement to the External with an MSA - 5, value “D” for Delayed Acknowledgement. The External receives the ACK, validates the ACK (verifying that it is a Delayed ACK), and waits for another ACK.

  3. The Inbound Adapter creates a JMS message with the HL7 message as the payload, creates a “reply to” destination, and forwards the HL7 message to the Outbound Forwarder (to a JMS destination).

  4. The Outbound Forwarder gets the HL7 message and forwards the message to the External System.

  5. The External System receives the HL7 message and returns the HL7 ACK message to the Outbound Forwarder.

  6. The Outbound Forwarder gets the HL7 ACK message and sends it to the Inbound Receiver Adapter using the “reply to” destination.

  7. The Receiver External reads the HL7 ACK message and forwards the second HL7 ACK message with an MSA - 5, value “F”to the Sender External. The Sender External then takes the appropriate action: for example, journaling the HL7 message and the HL7 ACK.

Message Verification

Message verification begins with reading the message from the external system. The message is expected to match the MLLP envelope, since both HLLP and MLLP envelopes have the Start of Block (SOB), End of Data (EOD), and a Carriage Return (CR) in common.

If a message fails the read verification, it is considered bad data. If read by an inbound Adapter, this failure causes the Adapter to generate a Canned HL7 NAK. An outbound Adapter ignores the message and logs a warning, reporting the nature of the problem to the log file.

An HLLP envelope needs further verification as to whether it is data or a NAK, as well as the Block Checksum and Block Size. The Adapter behaves as described above if the HLLP envelope verification fails.

After stripping the message envelope, the RA hands the de-enveloped message to the inbound Collaboration where it is parsed into the generic event Message Library. This ensures that the general form and MSH segment are valid. If the MSH property is set, the Collaboration verifies that the fields specified in the HL7 segment section are the same as those of the received MSH, otherwise, a NAK is returned.

Acknowledgment Processing

Recourse Actions

Recourse actions can be configured for an inbound Adapter for the following conditions. For more information, see Recourse Actions.

Outbound Functionality

The outbound TCP/IP HL7 Adapter Project, prjHL7Outbound, can be implemented in standard outbound mode or in two forward message modes: outbound delayed ACK or outbound forwarder.

Outbound Adapter Data Flow

In outbound mode, the Adapter receives HL7 messages from a JMS queue. Each message is verified to ensure it contains HL7 data only. Legitimate HL7 data is enveloped into its configured format and sent to the external system.

A message in the JMS queue triggers the outbound Collaboration. The outbound Collaboration is provided with an HL7 message to send to the external system

The Adapter waits for a configurable number of milliseconds for an incoming HL7 ACK or NAK from the external system. After receiving an HL7 response from the external system, the Adapter strips the message from its envelope and verifies its integrity.

Any non-HL7 acknowledgment received from the external system causes the Adapter to resend the same message. If the incoming response is an HL7 ACK or NAK, the Adapter might do either of the following, as dictated by its configuration:

If journaling is set, these messages and their ACKs are placed in the journal file.

Outbound Standard Messaging Mode

    The following steps describe the process for the Outbound Standard Message Mode:

  1. An HL7 message triggers the Collaboration. The outbound Collaboration is designed to accept the HL7 messages.

  2. The Collaboration maps the received message into the Generic Event Message Library and validates the MSH segment. If validation is enabled, the Collaboration checks the MSH segment of the outbound messages against MSH values configured in the Adapter properties file. If the validation fails or the message cannot be parsed, the message and its error are written to the error queue. Note that the HL7 message is always checked for structural correctness.

  3. The Collaboration sends the message to the RA.

  4. The RA envelopes the message and sends it to the External System and waits for an ACK.

  5. The Collaboration receives and validates the ACK, and then journals the ACK and the HL7 message (if journaling is enabled). If the Collaboration receives a NAK, the NAK and the HL7 message are sent to the error queue.

  6. Finally, the Collaboration commits the JMS receive.

Outbound Adapter Roles for Delayed ACK Scenarios

The outbound Adapter can fulfill two roles in a delayed ACK scenario. The outbound delayed acknowledgement mode is used to communicate with an external system that is configured to receive messages in a delayed ACK way; that is, it receives two ACKs. One confirms the message was received, and the other is from the application that accepts the message. For delayed ACK mode, the process is similar to that of the standard outbound mode, except that it receives two ACKs. The initial ACK comes from the receiving system.

Outbound Delayed ACK Role

The following steps describe the outbound delayed acknowledgement role process displayed:

  1. The outbound Adapter, which is configured as Delayed Acknowledgement role, receives a message from JMS, and sends the message to the External System.

  2. The External System receives the message and returns the first Acknowledgement to the outbound Adapter with an MSA - 5, value “D” for Delayed Acknowledgement. The outbound Adapter receives the ACK, validates the ACK (verifying that it is a Delayed ACK), and waits for another ACK.

  3. The outbound Adapter receives another HL7 ACK message (the second) and validates that the second HL7 ACK message is an MSA - 5, with a value of “F.” If the second ACK is valid, the Adapter commits the message, otherwise it resends the message.

Outbound Forwarder Role

The Outbound Forward Message role is used in conjunction with the with the inbound Adapter, which is also configured to handle delayed ACKs. No validation is preformed: the Adapter acts as a “pass-through.”

    The following steps describe the Outbound Forwarder Role processing:

  1. Data is received by the Collaboration, from the JMS queue.

  2. The Collaboration extracts the JMS property “reply to” destination from the message, but does no validation, and sends the message to the External System.

  3. The Adapter receives the ACK from the External System.

  4. The Collaboration sends the ACK to the temporary topic that was contained in the “reply to.”

    Note –

    For Delayed ACK, the Receiver and Forwarder must be on the same integration server.

Message Verification

The only verification that the outbound Adapter does is to ensure that the message parses into the generic Event Message Library, and that the MSH uses the correct fields. The acknowledge is verified to ensure that the sent message is valid.

Acknowledgment Processing

Recourse Actions

Recourse actions can be configured for the outbound Adapter for the following conditions:

General Functionality

This section explains the Adapter’s general functions and features. It includes the following topics:

Non-blocking I/O

The non-blocking I/O feature prevents the Adapter from locking up when attempting to read or write data blocks, allowing the Adapter to continue its operation in case of any communication errors. If the read attempt fails for a configurable number of times, the Adapter exits or resets its connection to the external system, depending on its configuration. In the event of a failed write, the Adapter can resume its write operation to pick up where it previously left off until the entire message is successfully sent.

Without this feature, the Adapter might lock up when a read or write failure occurs and be unresponsive to all external messages, including requests from the user or the Enterprise Monitor (for status).

HL7 Sequence Numbering Protocol

The Adapter can be configured to use HL7 sequence numbering. The negotiation and incrementation of this number is automatically performed by the Adapter. For more details on HL7 sequence numbering, refer to Appendix C (Lower Layer Protocols) of the HL7 Standard for the HL7 version you are using.

When the Adapter is configured for HL7 sequence numbering, the sequence number file opens when the Adapter starts up. If the sequence number file does not exist, one is created and populated with a zero sequence number. The sequence number file is updated on the inbound Adapter when the Adapter generates the HL7 ACK (this process is transparent to the user), and when the outbound Adapter receives the HL7 ACK from the external system.

If you want to change the sequence number at runtime, you need to suspend the Adapter, edit and save the sequence number file, and reactivate the Adapter. To force the Adapter to resynchronize its sequence number with the external system, you need to suspend the Adapter, edit the file so it contains a “-1”, and then reactivate the Adapter.

The minimum HL7 sequence number is 1. The maximum HL7 sequence number is 2 billion. A sequence number of “0“ is used to start a session. If the sequence numbers between the Adapter and the external cannot be reconciled during start or when exchanging messages, the Adapter shuts down and wait for human intervention as dictated by the HL7 Standard.

Failed Message Handling

The Adapter can be configured to send failed or skipped messages (destined for the external system) to a JMS-based error queue. Messages that fail validation are also written to the error queue. Note that the inbound mode of the Adapter will not write messages that fail the MLLP and HLLP validation. These are automatically NAKed and not passed to the Collaboration, but are logged to the Adapter’s log file.

The failed or skipped message is written to the JMS queue and the error type and message are written as the JMS properties:

Skipped messages are those which are continuously NAKed by the external system and thus are skipped if the Adapter is configured accordingly. If the Adapter is configured for any other recourse action other than skip, the message remains in the queue.

Recourse Actions

The TCP/IP HL7 Adapter recourse actions include Reset, Resend, Skip Message, and Exit.

Stopping the Collaboration with a Fatal Alert

When the Exit recourse action is triggered it logs the error that caused the action. It also shuts down the Collaboration, which in turn causes the HL7 message to roll back, and then sends an alert to the Enterprise Manager.

The Exit Recourse Action calls the fatal alerter in the Collaboration:


alerter.fatal(’’error message’’,’’HL7’’);

The argument error message is the user-configured alert message. The argument HL7 is the source component (this must be “HL7”).

Note –

The alerter.fatal("error msg", "HL7") method is only applicable to the packaged TCP/IP HL7 Collaborations.

The Exit recourse action should be applied to any error condition that requires human intervention to correct an error. Once the error condition is resolved, the Collaboration can be restarted from the Enterprise Manager.

TCP/IP HL7 Adapter Operation

The following topics explain the basic elements of the TCP/IP HL7 Adapter’s general operation:

Direction

The TCP/IP HL7 Adapter can be configured as either HL7 inbound or HL7 outbound. This option is determined automatically by the Adapter’s binding (link) in the Connectivity Map.

Connection Type

The connection type indicates how the Adapter establishes a TCP/IP connection. The role can be as a Client, where the RA connects to the external, or as a Server, where the RA waits for a connection.

Lower Layer Protocol

This section describes the two supported envelope types used in the HL7 protocol:

Both envelope types use the following configuration parameters. For more information on these parameters, see Lower Layer Protocol — TCP/IP HL7 V2 Inbound Adapter or Lower Layer Protocol — TCP/IP HL7 V2 Outbound Adapter.

MLLP

The MLLP envelope consists of a Start of Block component, a Data component, an End of Data component, and an End of Block component. The size of the HL7 Data field is determined by the length of the data (number of bytes between start and end), with a maximum size of 99999 Bytes.

HLLP

The HLLP envelope consists of a Start of Block component, a ”D’ (Data) or ”N’ (NAK) indicator, an HL7 Version component, a Carriage Return, a Data component, a Block Size component, a Block Checksum component, an End of Data component, and an End of Block component. The size of the HL7 Data field is determined by the length of the data (number of bytes between start and end), with a maximum size of 99999 Bytes.

HL7 Acknowledgment Level

The Adapter supports sending and receiving both HL7 acknowledgement types:

Journaling

The Adapter provides the option to journal successfully received or sent messages and their corresponding ACKs. The messages are sent to a JMS queue or topic, depending on how you configure the Adapter, and the ACKs are stored as a JMS property, HL7_ACK, of that message.

It is expected that, when enabled, the journal queue has one or more subscribers that process the contents of the queue so that it remains manageable. For example, the Batch Adapter or a database Adapter could periodically consume the messages by writing them to a file or a database.

Error Queues

The Adapter provides a mechanism to store failed or stripped messages in a JMS queue or topic. The advantage of this is that the messages are then saved in a form readily usable by the other data flows, that can automatically process these messages or make them available to some type of human intervention or message repair, using tools like the JMS queue editor or an eVision application.

Alerts and Monitoring

If the Adapter loses the connection to the external system in any direction or connection type, due to a crash, shutdown, or suspension (including recourse actions), an alert is generated. The monitor’s status of that Adapter is changed to “down” and the Adapter’s icon is encased in a red warning box. The monitor also displays the number of messages it has processed along with the date and time of the last message sent.

Support for HL7 Version 2.5 SFT Segments

HL7 version 2.5 adds a new SFT segment to every message. The Adapter not only sends and receives messages with the new segment, it can automatically create and populate them, using information from the Adapter properties, for the outbound message and the ACK sent from the inbound mode. This feature is only available when the Version ID property is set to 2.5 or later.

Delayed Acknowledgements

The Adapter supports delayed acknowledgements in either direction and in a number of roles. This functionality is described in detail in Outbound Adapter Roles for Delayed ACK Scenarios.

Monitoring the HL7 Adapter

You can monitor the status of the HL7 Adapter in the deployed Projects that include the adapter. This includes viewing alerts and log messages, checking connector details, and monitoring external connections. This is done on the Enterprise Manager. For more information about using the Enterprise Manager Monitor, see Using Enterprise Manager Management Application in Java CAPS.

For outbound HL7 Adapters, periodic monitoring for external connections is performed. The time period is based on the value defined in the HL7 Adapter web application's deployment descriptor file, web.xml. Below is an excerpt from the file defining the time period.


<web-app>
...
...
<!--  Default monitoring period used in monitoring the 
external system connection  -->
<context-param>
<param-name>monitorperiod</param-name>
<param-value>2000</param-value>
</context-param>
...
</web-app>

Schematron Support in the HL7 Adapter

Schematron is supported for HL7 V3 Message Libraries. The Schematron uses the concept of finding tree patterns in the parsed document rather than the grammar. This approach allows representation of numerous structures that are inconvenient and difficult in grammar-based schema languages.

For example, the following file defines a Person element that includes a Name field and a Gender field:


<?xml version="1.0" encoding="UTF-8"?>
<Person>
<Name>Eddie</Name>
<Gender>Male</Gender>
<Person>

The above XML document can be validated against the below schematron, which defines a test for a Title field, a test for Name and Gender, and a test for the order of fields:


<?xml version="1.0" encoding="UTF-8"?>
<sch:schema xmlns:sch="http://www.ascc.net/xml/schematron">
<sch:pattern name="Check structure">
<sch:rule context="Person">
<sch:assert test="@Title">The element Person must have a Title attribute<sch:assert>
<sch:assert test="count(*) = 2 and count(Name) = 1 and count(Gender) = 1">The element
 Person should have the child elements Name and Gender.<sch:assert>
<sch:assert test="*[1] = Name">The element Name must appear before element
Gender.</sch:assert>
</sch:rule>
</sch:pattern>
</sch:schema>

In the HL7 Adapter, this schematron is useful for validating an HL7 V3 document against predefined schematron schemas that you write. You can also obtain schemas from organizations such as NHS and HL7.org. For example, NHS provides schemas for CDA documents.

Schematron Configuration in HL7 Adapter

You configure the schematron validation from the Connectivity Map Properties Editor. The Properties Editor includes two properties to support schematron validation:

API for Schematron Validation

The HL7 Adapter includes an API specific to schematron validation. This API is a wrapper of the Open source XSLT-based API available at http://xml.ascc.net/schematron/1.5. The API is an XSL file called metastylesheet (skeleton1-5.xsl). Applying the metastylesheet to the schematron XML document generates another XSL file. This XSL file can be applied to the input XML document to validate, which produces the output XML document that contains the results of the validation. This document can be embedded inside the V3 acknowledgement and can be sent to the original sender.

The metastylesheet can be extended and overridden so that you can customize the output XML document.

Example,

The following is an example of an output document generated after invoking the API using the XML input document and the schematron validation document described above.


<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<schematron-output phase="#ALL" schemaVersion="" title="" xmlns:
sch="http://www.ascc.net/xml/schematron">
<active-pattern name="Check structure"/>
<fired-rule context="Person" id="" role=""/>
<failed-assert id="" role="" test="@Title" location="/@Person[1]">
<text>The element Person must have a Title attribute</text>
</failed-assert>
<schematron-output>

Using the Schematron API

Perform the following to invoke the schematron API from a Java Collaboration:

Obtaining the Factory Object

Below is a sample call to the getSchematronValidatorFactory method.


com.stc.connector.hl7.schematron.SchematronValidatorFactory
  factory = com.stc.connector.hl7.schematron.SchematronValidatorFactory.
  getSchematronValidatorFactory();

Obtaining the Validator Object

Below is a sample call to the getDefaultValidator method.


com.stc.connector.hl7.schematron.SchematronValidator 
validator = factory.getDefaultValidator( domSource );

In the above example, domSource is the DOMSource object of the schematron XML.

Performing the Validation

Below is a sample call to the validate method.


com.stc.connector.hl7.schematron.ValidationOutput
   output = validator.validate( dataSrc );

In the above example, dataSrc is the source of the payload. The payload can be an entire V3 XML document or a CDA document.

The ValidationOutput object contains the resulting XML document as well as a method isValid(), which returns values when the validation has passed or failed.