Ensemble Virtual Documents
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
||Validation examines the DocType property of the document to see if it has a value.
||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.
||For most virtual document formats, this is the default setting. Both d and m are active.
||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.
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.
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
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
Determine how the routing process will validate documents, as controlled by your own Validation
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 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.
/// '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 ];
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:
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.