Settings for HL7 Routing Processes
HL7 routing processes have the following settings:
|Basic Settings||Business Rule Name||“Settings for Routing Processes” in Using Virtual Documents in Productions|
|Validation||section in this topic|
|Additional Settings||Act On Transform Errors, Act On Validation Errors, Alert On Bad Message, Bad Message Handler, Response From, Response Timeout, Force Sync Send||“Settings for Routing Processes” in Using Virtual Documents in Productions|
|Local Facility Application, Ack Type, NACK Code, Add NACK ERR, Response Target Config Names,||sections in this topic|
|Development and Debugging||Rule Logging||“Settings for Routing Processes” in Using Virtual Documents in Productions|
The remaining settings are common to all business processes. See “Settings for All Business Processes” in Configuring Productions.
Determines the ACK type (that is, AA or CA) if creating an ACK or NACK reply message locally. A is the default code. For further details, see “HL7 Acknowledgment (ACK) Mode.”
Add NACK ERR
If True, when generating NACK messages, append an ERR segment that containing the InterSystems error codes and error text; otherwise do not embed internal error state information in NACK messages.
Local Facility Application
Colon-separated LocalFacility:LocalApplication code that represents the facility and application that receive HL7 messages via this routing process. If this routing process creates its own ACK or NACK messages, Local Facility Application provides the SendingFacility:SendingApplication codes for the messages; otherwise, this setting is ignored.
Determines the NACK code type (that is, AE or AR) if creating a NACK reply message locally to report an error. E is the default code. For further details, see “HL7 Acknowledgment (ACK) Mode.”
Response Target Config Names
A comma-separated list of configured items within the production. If specified, this list identifies the destinations, in addition to the caller, to which responses will be forwarded. If empty, responses are only returned to the caller. This setting takes effect only if the Response From field has a value.
The Validation setting of an HL7 Message Router controls how the router validates the incoming message. If the incoming message fails the specified validation, InterSystems reports the failure in the event log, and the HL7 routing process passes the message to its bad message handler only; see the Bad Message Handler setting. If the message fails the specified validation but there is no bad message handler, an error is logged but the message is not sent to any target. If the message passes validation, the HL7 routing process sends the message to the targets specified by the routing rules.
Ideally, you can use routing rules and data transformations to ensure each message is acceptable to the target system, and can, consequently, avoid using validation. This ensures that all messages are processed by the appropriate target. If you enable validation, InterSystems applies the validation tests before the routing rules. Any message that fails validation will not be sent to a target based on the routing rules; it will be sent only to the Bad Message Handler. However, there are some environments where HL7 message validation is the preferred way to filter messages. For example, in the following situations, using HL7 validation is a good choice:
You are developing or debugging an interface and want to determine the kind of message variants that your system needs to handle.
The target application cannot handle messages that have variances from the specification, and the routing rules and transformations cannot resolve those variances.
There is a regulatory or other business requirement that the messages conform to the specification.
HL7 validation does add overhead to the routing process. This overhead can be significant and can reduce the maximum load of messages that your production can handle.
The Validation property allows you to specify flags that control the following:
Whether the message has a valid document type.
Whether the message structure is validated.
Whether trailing Z segments that are not specified in the schema are validated.
What specific field validations should be applied.
Whether the validation stops after reporting the first error or continues to validate the remaining segments and fields in the message.
If you specify an empty string as the Validation property value, the message router skips validation and routes all messages. When you create a new HL7 routing process in the Management Portal, the Validation setting is initialized to an empty string.
For compatibility with previous releases, setting Validation to 1 is treated the same as setting it to dm-z and setting Validation to 0 is treated the same as setting it to an empty string.
The message validation sequence is as follows:
Validate that the message object has a DocType property value.
Validate the segment order.
Validate the fields within segments.
If at any time during this sequence the message fails validation and the -x flag is not specified, the HL7 routing process does not validate the remaining segments of the message.
A message can pass validation and not conform exactly to the schema definition depending on the Validation flags specified.
Validating the DocType Property
The business service sets the DocType property value based on the Message Schema Category defined for the service and the document name specified in the HL7 message MSH:9 field. If the Validation property value includes d, the message router tests if the DocType property has a value. If it does not have a value, the message is a bad message.
The business service does not assign a value to the DocType property under any of the following circumstances:
The Message Schema Category is not specified for the business service.
The document name in the HL7 message is not defined in the specified schema or, for custom schemas, in either the specified schema or the base schema.
Validating Segment Order
This section describes how routing engines validate segments.
If the Validation property has a value of dm, dmz, or dm-z, the routing process validation either validates the message or declares it bad, by the following tests:
If the segments in the message conforms to the message structure specified by the DocType value that the business service assigned to the message, the m validation is satisfied. For example, if the message has a DocType value of 2.3.1 and the MSH:9 value in the message is ORU^R01 the message is verified against the ORU_R01 message structure under the 2.3.1 category. If the message data is missing some required segments, or if it has extra undefined segments, as compared to the 2.3.1 ORU_R01, then it is a bad message. HL7 allows custom local variations to be added to standard messages as trailing Z segments. A trailing Z segment in a message is validated governed by the following rules:
If the schema specifies the trailing Z segment or specifies the “Zxx” wildcard segment, the trailing Z segment passes validation.
If the -z flag is specified, the trailing Z segment in the message passes validation.
If the -z flag is not specified and the trailing Z segment is not defined in the schema, the trailing Z segment fails validation.
If the schema requires a trailing Z segment and the message does not contain it, then the message fails validation.
If the DocType refers to a custom schema, the same rules apply as in test 1, except that the message is verified against the custom definition. Each custom schema has a base category defined (for example base="2.3.1"). If a message arrives that is not explicitly defined in the custom schema, the base category is used.
If MSH:9 field can contain a nonstandard value, you must define a custom schema to avoid having messages with this nonstandard value fail validation. For example, if MSH 9 is equal to ORU^Z22 instead of ORU^R01 a custom schema is required to specify that the message name ORU^Z22 should be verified against the structure ORU_R01.
For information on creating custom schema categories, see “Creating Custom Schema Categories” in Using Virtual Documents in Productions.
The f flag enables all field validation. If you specify f, the message router performs the following field validation:
Tests that field and component order in the message conform to the schema.
Tests that required fields, components, and subcomponents are present.
Test that field sizes in the message conform to the schema.
Tests that field data values conform to the data type defined in the schema.
Tests that field data values conforms to the code tables, but allows any value if the code table includes the ... value or if the code table is empty.
Specifying Validation Flags
Each flag can be preceded with the - hyphen character to negate the meaning of the flag. For example, the x flag specifies that the routing process should stop validation after encountering the first error, and the -x flag specifies that the routing process should continue validation until the entire message is validated and all errors detected. Some validation flags are equivalent to specifying a series of flags. For example, the s flag is equivalent to specifying the jpw flags. You can remove one of the series by specifying a negating flag. For example s-p is equivalent to jw. To negate a flag, you must enter a hyphen immediately before the flag character. For example, if you want to negate both the z and x flags, you must specify -z-x.
The following table lists the HL7 validation flags and describes how the routing process validates the message when each is specified.
|a||Enforces field array repetition limits.|
|b||Interprets ... in a code table to allow any field value to pass validation.|
|c||Performs all component and subcomponent validation. Is equivalent to gijopw.|
|d||Requires that the DocType property be defined. Note that every other flag requires that DocType is defined in order to perform the specified validation.|
|e||Performs every validation. Is equivalent to abdgijlmnoprtuwy.|
|f||Performs all field validation within segments. Is equivalent to abgijlnoprtuwy.|
|g||Enforces data structures within segments.|
|i||Enforces component size restrictions.|
|j||Ensures that required subcomponents are present. These are governed by the optionality setting in the schema.|
|l||Enforces field size restrictions.|
|m||Ensures that all required segments in the schema definition are included in the message and that the message does not contain any misplaced segments that are not allowed by the schema.|
|n||Ensures that the segments contain the correct number of fields.|
|o||Ensures that required components are present. These are governed by the optionality setting in the schema.|
|p||Enforces component-level data structures.|
|r||Ensures that required fields are present.|
|s||Performs all subcomponent-level validation. Is equivalent to jpw.|
|t||Enforces code tables. This flag can be modified by the b and u flags.|
|u||Ignores code tables that do not list any permissible value. Permits any value for these empty code tables.|
|w||Enforces subcomponent size restrictions.|
|x||Stops validating after the first error is encountered. This is the default. -x specifies that the entire message is to be validated and all errors returned in the status.|
|y||Enforces field data types, such as numeric.|
|z||Requires that Z segments be explicitly specified in the schema or specified by the wildcard Zxx in the schema. -z allows trailing Z segments even if they are not specified in the schema.|
|(empty string)||Skips validation and routes all messages.|