Controlling Message Validation
For virtual documents other than ASTM documents, Ensemble can provide message validation, with an option to include a business host to handle bad messages. You can also override the validation logic, if wanted. This chapter describes the details. It includes the following topics:
Introduction to Message Validation
For virtual documents other than ASTM documents, one or more of the specialized business host classes include the Validation setting, which you use to specify how that business host should validate messages that it receives, before attempting further work.
If the message does not fail validation, the business host sends the message to the specified normal target or targets.
If the document does fail validation, the details are different depending on the kind of business host:
A business service or business operation does not send the message anywhere.
A routing process includes the additional setting Bad Message Handler, which is meant to be the name of a business host. If the document fails validation, the routing process forwards the document to its bad message handler, as specified by this setting. If there is no bad message handler, the routing process does not route the document, but logs an error. The routing process may also include a setting to enable you to send an alert.
Basic Validation Options and Logic
This topic describes the allowed values for the Validation setting and describes how Ensemble validates a message. (Note that HL7 Version 2 has an additional flag related to Z-segments and has additional logic; see the Ensemble HL7 Version 2 Development Guide.)
|d||Validation examines the DocType property of the document to see if it has a value.|
|m||Validation verifies that the document segment structure is well formed, and that it can be parsed using the schema identified in the DocType property of the document.|
|dm||For most virtual document formats, this is the default setting. Both d and m are active.|
|1||Same as dm, for backward compatibility with previous releases.|
|(a blank string)||The routing process skips validation and routes all documents as given in the associated routing rule set.|
The d Validation Flag
If the d flag is present in the Validation string, Ensemble examines the Schema Category specified in the message (as set by the business service) and compares it with the message DocType. If the Schema Category in the message is blank, the message is automatically declared bad. However, if Schema Category is not blank, but does not match the message DocType, validation can continue, as long as there are more Validation flags defined, such as m.
The m Validation Flag
If the m flag is present in the Validation string, Ensemble searches for a way to either validate the message, or declare it bad The details depend upon the virtual document type.
Overriding the Validation Logic
The virtual document routing process (EnsLib.MsgRouter.VDocRoutingEngine), and its subclasses provide default validation logic. Most of the specialized virtual document business service and operation classes also provide validation logic. You can override the validation logic; to do so, create and use a subclass of the applicable class.
Overriding the Validation Logic in a Routing Process Class
If you create a subclass of an Ensemble class and then override the OnValidate() method, you can:
Extend or replace the list of accepted values for the Validation setting.
Determine how the routing process will validate documents, as controlled by your own Validation options.
When you override the OnValidate() method, you may also override the Validation property definition in the same subclass. Pay careful attention to the following details:
The InitialExpression value specifies the default for the Validation configuration setting.
The comments that precede the Validation property definition are used as a tooltip for the Validation setting. Use the /// convention and leave no white space lines between the last comment line and the property definition. This allows Management Portal users to view your comments as a tooltip.
As an example, the following excerpt shows some of the comments that appear with the Validation property definition in the EnsLib.HL7.MsgRouter.RoutingEngine class:
/// 'd' - require DocType /// 'm' - don't tolerate BuildMap errors (includes 'z' by default; /// specify '-z' to tolerate unrecognized trailing Z-segments) /// 'z' - don't tolerate unrecognized trailing Z-segments Property Validation As %String(MAXLEN = 20) [ InitialExpression = "dm-z", Transient ];Copy code to clipboard
Overriding the Validation Logic in a Business Service or Operation Class
The virtual document business service and operation classes each provide a Validation property and OnValidate() method that you can override. By default, this property is not exposed as a setting for any of these business services or business operations, and by default, no OnValidate() activity ever occurs in these classes. You can change this if you want to validate documents at the incoming or outgoing sides of the interface, rather than at the routing engine as is the usual case. To accomplish this, follow these steps:
Use the instructions for overriding Validation and OnValidate() provided above.
If you want your users to be able to choose a type of validation, also add the Validation property as a setting. See “Adding and Removing Settings” in Developing Ensemble Productions.
Defining Bad Message Handlers
A routing process has the setting Bad Message Handler. The purpose of this setting is to indicate the business host to which the process should send messages that are found to be bad, according to the Bad Message Handler of the business process. To define a bad message handler, first decide how you want to handle the bad message. Typically you create a business operation. This business operation could do either or both the following, for example:
(Via a file adapter) Write the contents of the message to a file.
(Depending on a configuration setting) Trigger an alert whenever it encounters a bad message.
Note that the business process sends the bad message to this business host instead of its usual target for validated messages.
If a message is bad and if the Bad Message Handler setting is not specified, the routing process simply stops the validation sequence and does not send the message.