The HL7 Acknowledgement Generation filter can be used to create HL7 acknowledgment messages.

By default, the filter can generate acknowledgment messages of the 'ACK' message type for all HL7 versions. EDI message definitions are required if the filter is to be used to create acknowledgments of other HL7 message types. The filter is normally used in the following situations:

  • Creating positive acknowledgments for all messages received.
  • Validating messages (for HL7 syntax) and generating positive or negative acknowledgments based on the validation results.
  • Creating acknowledgments by using properties set on the input message as errors.

Configuration Properties

Property

Description

Message Definition

The EDI definition file for input messages and acknowledgments.

Response Message Mapping

Map input message type to acknowledgment message type.

Acknowledgment Mode

Sets the action to be taken by the filter. This allows the filter to make a decision on which acknowledgment needs to be generated after an input message is received.

  • Always ACK - the filter creates a positive acknowledgment always.
  • Always NACK - the filter creates a negative acknowledgment always.
  • Validate and NACK - the filter validates input message against configured message definition and creates an acknowledgment (positive or negative) from the validation results.
  • Use properties and ACK - the filter checks for errors set as properties on the input message and creates an acknowledgment with the content of these properties.
  • Validate, use properties and ACK - filter first validates the input message and then checks for any errors set as message properties. An acknowledgment is created containing all the errors (if any).

NACK mode

The acknowledgment mode of the acknowledgment message. Defaults to AR.

User Description

Any text provided here will be used as the content of the MSA.TextMessage field of the generated acknowledgment.

On message validation failure

Action to be taken by the filter when the input message contains errors or error properties. Available options are:

  • Return ACK only to route. (default).
  • Return input message only to route.
  • Send input message to error connector.
  • Return both input message and ACK to route.

On successful validation

Action to be taken by the filter when the input message does not contain errors or error properties or if the Acknowledgment Mode is configured as Always ACK. Available options are:

  • Return ACK only to route (default).
  • Return input message only to route.
  • Return both input message and ACK to route.

Message Errors Property Name

A list of the names of properties in the input message containing message errors (in Rhapsody's specified error message format) generated by HL7 External Code Translation and HL7 External Code Validation filters. The HL7 Acknowledgement Generation filter generates a NACK using these properties.

HL7 version

The HL7 version of the acknowledgments to be generated. The available options are:

  • Same as input message (default) - the filter creates acknowledgments based on the HL7 version of the input message. This is the recommended option.
  • 2.1, 2.2, 2.3, 2.3.1, 2.4, 2.5, 2.5.1 or 2.6 - the supported HL7 version.

Maintain Field Length

The action the filter should take when creating ERR segments. This entry can be used to control the length of the error text in the ERR segment. Available options are:

  • Ignore error length - the filter will not perform any checks or any action on the generated ERR segment.
  • Use HL7 version 2.5 specs - the filter will allow the generated ERR segment to be a maximum of 493 characters long (as in the HL7 version 2.5 specification). Longer error messages will be truncated to fit the 493 character limit.
  • Use HL7 version 2.1 to 2.4 - the filter will allow the generated ERR segment to be a maximum of 80 characters long (as in HL7 specification versions 2.1 to 2.5).

Fields to Copy

Enables you to map fields in the input message (Source Field) against fields in the generated acknowledgment (Destination Field). This mapping allows the filter to copy across content from the input message into the generated acknowledgment. By default, the filter copies the following fields:

An ACK can be generated of an HL7 version that is different to the version of the incoming message by explicitly specifying the HL7 version in the HL7 version property. However, if a mapping is specified in the Response Message Mapping property, then any messages which are mapped according to that setting use the message structure from the EDI definition file specified in the Message Definition property. Consequently, it is important that the MSH and MSA segments in that message definition match one of the HL7 standards otherwise it is possible that errors may occur while generating the acknowledgment.

If a non-standard acknowledgment message structure is required then it is recommended that a standard acknowledgment is generated using this filter, and then the Mapper filter is used to transform it into the desired structure.

Error Message Format

The filter reports errors using the standard HL7 ERR segment format. The HL7 version used for the ERR segment by the filter is determined by the HL7 Version configuration property:

'HL7 Version' Configuration Property HL7 Format for ERR Segment Description Example
2.1 HL7v2.1  Each error is separated by spaces (does not support repeats). ERR|1005 MSH/MessageControlId Required field missing~1010 MSH/SendingApplication/NamespaceID Field too long 
2.2 to 2.4 HL7v2.4 Each error is a repeat in the ERR segment (separated by '~'). ERR|MSH^1^10^1005&Required field missing&&&MSH/MessageControlId~MSH^1^3^1010&Field too long&&&MSH/SendingApplication/NamespaceID 
2.5 to 2.6  HL7v2.5 Each error is an ERR segment repeat. ERR||MSH^1^10^1|101^Required field missing^HL70357|E|1006^Required field missing|MSH/MessageControlId
ERR||MSH^1^3^1^1|207^Application internal error^HL70357|E|1008^Field too long|MSH/SendingApplication/NamespaceID 

Additionally, the maximum length of the ERR segment can be set through the Maintain Field Length configuration property.

For examples of the types of error codes you may encounter, refer to Error Codes for EDI Designer.

Published Properties

Published properties for the HL7 Acknowledgement Generation filter are as follows:

Published Property

Description

AckStatus

This property is set on all messages where some action is taken by the acknowledgment generator:

  • ACK - a positive acknowledgment was generated and sent to the source system.
  • NACK - a negative acknowledgment was generated and sent to the source system.
  • BADHL7VERSION - this message has an HL7 version which is not accepted by this filter.
  • NOTHL7MSH - this is not an HL7 message.
  • UNKNOWNHL7MSG - this message appears to be a valid HL7 message, but is unknown by this filter.

AckCode

The response code that was sent with the generated acknowledgment. If an acknowledgment message was not created, then this property is not set.

AckIsValid

A boolean property that is set to True if there were no validation errors in the message, or False if there were any validation errors. If the message was not validated, then this property is not set.

AckMessageType

This property allows the original and acknowledgment messages to be easily distinguished (for easy routing).
The input message will carry the value for this property as ORIGINAL.
The acknowledgment message will carry the value for this property as ACK.

MSG_CTRL_ID

The property that is common to both the input message and the generated acknowledgment. This property can be used in the collation process to pair up the input message and the generated acknowledgment.

ValidationErrors

If the filter is used to validate and return the input message, then all the validation errors found will have been set as the value of this property (in Rhapsody's error message format).