Managing a Healthcare: HL7 to HL7 DFDL 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:

runmqsc queue_manager < queues.mqsc

where queue_manager is the name of the queue manager for your integration node

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 HL7 DFDL library

Download one of the HL7 DFDL libraries, see Resources for the Healthcare: HL7 to HL7 DFDL pattern.

By default, the application generated by the pattern uses the HL7 v2.7 DFDL model. If you want to use the HL7 v2.6 or HL7 v2.5.1 DFDL models, complete the following steps:

1. Update the reference in the application that is generated by the pattern, so that it refers to the required HL7 library. To change the reference, right-click the generated application and click Manage Library references.
2. In the Receiver.esql file, edit the value of the ReceiverMessageSet constant:
   • To use the HL7 v2.5.1 DFDL model, change the value to HL7v251DFDL
   • To use the HL7 v2.6 DFDL model, change the value to HL7v26DFDL
3. In the Application Development view, select your generated application.
4. Click Project > Clean. The Clean window opens.
5. Select Clean all projects and click OK.

The DFDL libraries meet the standards set out in the HL7 v2.5.1, v2.6 and v2.7 standards. The message used by the pattern is the HL7 message in the segments.xsd 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 HL7 DFDL library.
• 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 your own Z-segments and use them in your applications. Each DFDL model library contains a Z_Segments.xsd file, which you can customize by adding your own Z-segment definitions.

Z-segment definitions, that are added to the choice group of the Z_Group definition in the Z_Segments.xsd file, are used to parse any un-modeled segments. The element named Zxx is added to this group by default. The Zxx element has no specific initiator definition for the segment, so all segment content is modelled by the Remainder field.

Complete the following steps to create a new Z-segment definition.

1. From the DFDL model library, open the message definition file Z_Segments.xsd with the DFDL editor.
2. Create a new element for the segment that is defined outside the HL7 specification. You can either create a new global element and add a reference to the element in the choice group of the Z_Group definition, or you can add a local element directly to the choice group of the Z_Group definition.
3. Either delete the default Zxx element (if it exists), or make sure that the Zxx element is the last entry in the choice group of the Z_Group definition.

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 Dest n , 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

Deploy the generated application which has reference to HL7 DFDL library and sub flow library.

1. 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.