Managing a Healthcare: HL7 to HL7 pattern instance

Set up

Queues

You can choose to generate an MQSC script for defining the queues that are required by the pattern by selecting the Generate scripts check box in the General section of the Configure Pattern Parameters tab, before you generate the pattern instance. This script, which is called queues.mqsc, is in the root directory of the pattern instance project; it defines basic queues and topics.

You can run the MQSC script by using the following command, where MBQMGR is the name of the queue manager for your integration node:

runmqsc MBQMGR < queues.mqsc

You can edit this MQSC script to add descriptions for your environment and to set appropriate queue depths.

In particular, you must check the depth of the queue, flowprefix.DUPID, which holds the duplicate data store. This queue stores all data that is used for duplicate checking. If duplicate checking is enabled, the required depth of this queue is calculated by multiplying the maximum receiver message rate by the duration of the expiry setting. For example, if the maximum rate is 10 messages per second and the expiry setting is 24 hours (86,400 seconds), the required depth is 864000 .

It is expected that other queues are monitored and regularly cleared. These queues are created with a default size, but you must review their use and ensure that the depth is sufficient.

You must run the MQSC script before you deploy the pattern instance.

Configurable service

If you have switched on sequencing and selected the option to separate sequence queues, the pattern generates a configurable service file. This file is created when you generate an instance of the pattern, in the root directory of the container project that contains the generated message flows. This configurable service provides information to the Resequence nodes about where to store sequencing information. The configurable service must be deployed to the integration node before the pattern is deployed.

Preparing the HL7v25P message set

Download the HL7v25P message set, see Resources for the Healthcare: HL7 to HL7 pattern.

This message set meets the standards set out in the HL7 v2.5 standard. The message used by the pattern is the HL7 message in the segments.mxsd message definition file. If source or destination applications make modifications to the standard, these modifications must be reflected in the message model. The most likely modifications are:

Modification to the mandatory setting of the fields that are defined in the message model by changing the Min occurs or Max occurs parameter values.
Creation of any Z-segments that are used by source or destination applications. Z-segments model application-specific data that is not defined in the HL7v25P message set.
Vendor-specific modifications or additions to the standard.

Creating a new Z-segment

Z-segments are used by applications to send or receive data that is defined outside the HL7 specification. You can model Z-segments and use them in your implementation:

Create a new message definition file. This file keeps application specific code separate from the main HL7v25P message set. Right-click the HL7v25P message set, select New > Message Definition File .
Set the Target Namespace property of this message definition file to urn:hl7-org:v2xml
Open the new message definition file and select the Properties tab. Add the datatypes.mxsd file.
In your new .mxsd file, create a new global element with the same name as the Z-segment definition provided by the source or destination application.
Change the Type of this element to New local complex .
Create individual fields as local elements. If the Z-segment has fields that have child fields, select an appropriate Type for the element from the menu by clicking More . These types are defined in the fields.mxsd file. Ensure that the resulting structure matches the specification from the source or destination provider.
Add the new element to the HL7 message:
1. Open the segments.mxsd message definition file, select the Properties tab, include the new message definition file that you created, and save the change.
2. For the new element that you created, add an element reference to the HL7 message:
  1. In the segments.mxsd message definition file, expand the HL7 message.
  2. Right-click Choice and select Add Element Reference .
3. Open the properties of the global element you created and set the tag to be the same as the element name.
For each element in the the new Z-segment, open the properties and set the namespace to urn:hl7-org:v2xml

Vendor specific additions to the HL7 standard

HL7 implementations might make additions to the standard segments, as defined by HL7, by adding additional fields to the end of a segment. These additions are generically modeled by a Remainders field at the end of each segment definition. However, you can add the additional fields that are required by vendors before the Remainder field.

Customization

Three main customization points are available to users of the pattern, but additional customization points are also available.

Source customization

The main TransformAndRoute message flow calls the SubCustomize subflow before distributing the message to different destinations and before creating the canonical form of the message, if required.

The default SubCustomize subflow has no effect on the message, but you can use this customization point to standardize data from the source to meet your requirements. For example, you might have a standard for dates in the format YYYY-MM-DD , but the source uses a different date format. You can use this customization point to modify any source data. Additionally, you might choose to include data at this point that is available from other sources, such as databases.

Destination customization

For each destination there is a default customization subflow (named Destn, where n is the number of the destination) that has no effect on the message, but you can use this subflow to build an output message that matches the specifications required by that destination. For example, the destination might require the following changes:

Additional data that is required in Z-segments
Modification of data from the source; for example, formatting the date of birth of a patient based on destination date format requirements
Deletion of data not required or supported by the destination

Use of Source or Canonical feeds

If you have chosen to generate a source feed or a canonical feed, each message processed by the Receiver flow generates a copy of the source message or the message after canonicalization. These messages are written to a WebSphere MQ queue or published as determined by your pattern parameters.

You might want to send messages to destinations that are not compatible with the pattern, for example, to a data warehouse, a non-HL7 destination, or a destination that uses a different transport mechanism. You can send messages to destinations that are not compatible with the pattern by writing integration solutions to process the messages from the source or canonical feeds.

Pattern deployment

Create a new BAR file in the location where you want to store these resources.

The HL7v25P message set must be packaged in its own BAR file:

Select the HL7v25P message set, and build the BAR file.
Deploy the BAR file to all integration servers on which you want the pattern, or parts of the pattern, to run.
After the HL7v25P message set is deployed, ensure that all required queues are defined and that any configurable service files are deployed.
Create one or more BAR files that contain the flows that you want to deploy to a specific integration server. In the simplest case, where everything runs in a single runtime environment, include the Receiver flow, TransformAndRoute flow, and all destination flows.
To gain improved performance after the flows have built, you might want to increase the Additional instances setting for any flow that does not have sequencing requirements:
1. Click the Manage tab.
2. Select the properties of flows that you want to configure, and set values that are required by your implementation.

Monitoring and Error handling

Error notifications are written to an error queue for all message flows in the pattern. A queue trace is also output to the location that you defined during pattern generation. The MQRFH2 header of the error message contains information indicating where the error occurred. Details about the behavior of each message flow are specified in this section.

Errors in the Receiver flow

The Receiver flow is run as a transaction and all output messages are committed on successful completion of the message flow. If acknowledgments are required, the last action of the Receiver flow is to send the acknowledgment (ACK). When processing the acknowledgment is successfully completed, the flow ends and the messages are committed.

For each action in the Receiver flow:

The FlowMilestoneReached parameter is set before the action is started; the parameter indicates the part of the flow where the error occurred.
The ErrorCondition message gives details of the error that occurred.

If there is an error, the following events occur:

The error is caught and processed by the ReceiverExceptionHandler subflow. This subflow adds MQMD and MQRFH2 headers to the message and writes the message to the error queue outside the transaction. The MQRFH2 header contains details about where the error occurred.
If required, a negative acknowledgment reply (NACK) is generated and sent to the source application.
An exception is thrown, which rolls back all messages and, if arrival based sequencing is required, assigns a sequence number. The rollback also triggers the output of the exception information to the Event log.
The flow behaves as if no message has been received, and either a corrected message is resubmitted or the information is processed at the destination application.
The NACK that is sent to the receiving application indicates that the message has not been processed.

The administrator must monitor the error queue and Event log to determine when messages have not been processed by the receiver queue, and take the necessary remedial action to resolve the error.

Errors in a TransformAndRoute flow

A TransformAndRoute flow is run as a single transaction. On successful completion of the message flow, all output messages are committed to the following locations:

The input queue for the Sender flow for each destination
The Remainder report (if selected)
The Queue for the canonical message feed

If there is an error, the following events occur:

The error is caught and processed by the TransformationExceptionHandler subflow. This subflow adds an MQRFH2 header to the message and writes the message to the error queue outside the transaction. The MQRFH2 header contains details about where the error occurred.
An exception is thrown, which puts the input message back onto the queue, rolls back any messages written to queues, and triggers the output of the exception information to the Event log.

The administrator must check the error queue and Event log to determine what errors have occurred. Both the error queue and the backout queues contain information, and after a corrected message is processed this information must be cleared to prevent the queue from filling.

The administrator must configure a backout queue for the input queue.

When a message is rolled back by the Routing and Transformation flow, later messages are still processed and passed to the Sender flows. However, this action can have an effect on the Sender flows for any destination that implements either lax or strict sequencing because the sequence number of the message in error is missed, which causes messages to queue on the sequence queue until either a message with the correct sequence number is received or, in the case of lax sequencing only, the message times out allowing the missing sequence number to be skipped. Therefore, errors in the TransformAndRoute flow must be corrected as soon as possible.

Two options are available for correcting an error in the TransformAndRoute flow:

A corrected message can be submitted to the TransformAndRoute flow. You can edit the message written to the error queue or the backout queue and then resubmit the message. This action ensures that the sequence numbers are correct.
The information in the error message can be applied directly to the destination applications. If strict sequencing is used for a destination, you must send a dummy message to that destination to allow the flow of messages to continue:
1. Create an XML message. For example:
```
<sup:MaintainSequence xmlns:sup=http://ibm/healthcare/support>
    <MessageGeneratedToMaintainSequence>true</ 
    MessageGeneratedToMaintainSequence>
</sup:MaintainSequence>
```
2. Put this XML message on the required destination queue. You must set the following two values for the MQRFH2 header user folder, where the sequence number element contains the message sequence to skip, and the sequence group element specifies the destination that the message references. For example:
```
<SequenceNumber>2</SequenceNumber>
<SequenceGroup>DEST1</SequenceGroup>
```

Errors in a Sender flow

The Resequence node, named Maintain Sequence, is included in Sender flows that support sequencing. A Resequence node divides the flow into two transactions. If an exception occurs before the Resequence node, a message is written to the error queue outside the transaction, and the input message is rolled back to the input queue for the Sender flow. The input queue must be configured with a backout queue.

This type of error handling also applies if the Sender flow has no sequencing.

Use one of the following solutions to correct the error:

Correct and resubmit the message.
Apply the event directly to the destination application and submit a dummy message.

Errors at this point in the flow mean that a sequence number is missed. If sequencing is used for the Sender flow, the administrator must review the error queue and correct the error as soon as possible. Later messages in the sequence are saved on the internal sequence queues; an error can therefore result in a build up of messages.

If an error occurs after the Resequence node but before the message is sent to the destination application, an error message is written and the message is backed out onto the internal sequence queue. To resolve this type of error, the administrator must ensure that the destination application is both available and connected. The Resequence node continues trying to deliver the message so that the message is delivered when the connection is made, and, in the case of strict sequencing, later messages are not delivered until the earlier delivery succeeds.

An error can also occur after a message is delivered. This type of error happens if the destination application cannot process the message and sends a NACK. In this case, the flow does not back out the message to the Resequence node because the message might cause the same error repeatedly. Instead, a message is written to the error queue. The administrator must check the error message and correct the problem at the destination application. In this case, messages with a higher sequence number continue to flow.

The main information available for administrators who are resolving errors is the information contained in the messages on the error queue and the backout queues. However, the SEQNOS queue is also available, which stores the state of the current sequence information. You can use this queue to give an overview of the flow of the messages to each of the pattern destinations.