1. Problem
You need to implement custom
logic within a pipeline for an integration solution you are building.
Based on the solution's requirements, message delivery must be
guaranteed, with no messages being lost once they are received by
BizTalk Server. Any errors within the custom pipeline must result in a
notification e-mail being sent to the appropriate system administrators.
2. Solution
BizTalk Server 2010 has some
very convenient, easy-to-use error-handling functionality called error reporting,
which enables simplified handling of pipeline (and other) errors. Error
reporting is specified on receive and send ports within the BizTalk
Administration Console, as shown in Figure 1.
By enabling this feature on a
port, you instruct BizTalk Server to take a number of steps in the event
an error is encountered during message processing (which includes
adapter, pipeline, mapping, and routing processing). Specifically, a
clone of the errored message is created, with all the original promoted
properties demoted. The message does, however, have the appropriate
error reporting properties promoted, such as the failure code and
receive port/send port name. This message is then delivered to the
MessageBox, and can be subscribed to by an SMTP send port via the error
reporting promoted properties. This SMTP send port can be configured to
deliver notification messages to a system administrator.
NOTE
If error reporting is
enabled, and an error occurs when BizTalk Server attempts to deliver the
cloned message to the MessageBox, the original message is placed in the
suspended queue.
3. How It Works
Error reporting allows a
variety of receive/send port errors to be trapped and managed. The
details of the error are promoted as properties on a copy of the
original message, which is sent to the MessageBox database. This allows
you to handle error messages just like any other message: via
subscriptions. You can define error-handling mechanisms specific to a
single integration point, an application, or an entire BizTalk
environment. Your error-handling mechanisms can be a simple notification
e-mail (as shown in this solution), or a complex set of processes
implemented as orchestrations.
The Error Reporting
properties are available on Filters in send ports and orchestrations
(See Figure 2). This allows messages to be routed to
the appropriate destinations.
Table 1 shows the error-reporting properties promoted on errored
messages.
Table 1. Error-Reporting Properties Promoted on
Errored Messages
| Property | Description |
|---|
| FailureCode | The code identifying the
error. |
| FailureCategory | The category of the
failure. |
| MessageType | The
BizTalk message type of the failed message. This property may be empty
if BizTalk Server could not determine the type of message. |
| ReceivePortName | The
name of the receive port where the failure occurred. This property is
populated and promoted only if the failure occurred on a receive port. |
| InboundTransportLocation | The
URI of the receive location where the failure occurred. This property
is populated and promoted only if the failure occurred on a receive
port. |
| SendPortName | The name of the send port where the
failure occurred. This property is populated and promoted only if the
failure occurred on a send port. |
| OutboundTransportLocation | The
URI of the send port where the failure occurred. This property is
populated and promoted only if the failure occurred on a send port. |
| ErrorType | The
type of message that the error report contains. |
| RoutingFailureReportID | The
ID of the related routing failure report message in the MessageBox. The
routing failure report message contains the properties (context) of the
original message and can be queried to provide additional information
about the errored message. |
