Error handling and exceptions are the bane of all BizTalk integration projects. When too many errors occur, people begin to wonder why your company continues to use an integration application. It you automatically handle too many errors during development, your application will never advance beyond the testing stage. You simply cannot conceive of every possible error. At some level, you need to build human intervention into the application.
Human intervention for error handling often requires business knowledge as well as access to the tools to handle the exception. How do you allow for human intervention without requiring that all your application business users become BizTalk Server administrators or all your administrators become proficient business users? BizTalk 2006 failed message routing and InfoPath may be just the solution for you.
Using a sample garnered from the BizTalk 2006 SDK, this article shows how to implement human intervention features into your error handling.
Before jumping into the sample, an explanation of failed message routing would be helpful.
New in BizTalk 2006: Failed Message Routing
The BizTalk 2006 documentation includes a complete explanation of failed message routing. This section summarizes that documentation.
Failed messages are error messages resulting from processing errors in pipelines or adapters, or errors related to message routing. Thus, failed messages can result from exceptions on a send or receive port. So, for example, exceptions in a pipeline or a delivered message without subscribers would create a failed message.
Failed message routing is new in BizTalk 2006 and must be enabled on the port. Failed message subscribers can subscribe to information contained in the context of the error message. Error message context contains things such as port name, type of failure, and failure description. Subscribers can be either orchestrations or send ports.
You can use failed messaging for a variety of different error-handling scenarios ranging from simple notifications to a completely separate human workflow process. The sample in this article combines failed message routing with a BizTalk orchestration and InfoPath to fix errors and resubmit to BizTalk.
The error-handling sample simulates an expense submission system. Figure 1 provides a graphic overview of the sample; Figure 2 shows where it is located.
Figure 1: Error-handling Sample Overview
Figure 2: Location of Error-handling Sample
Expenses are loaded into an InfoPath form (see Figure 3) and submitted to a simulated “backend” system via the BizTalk file adapter.
Figure 3: An InfoPath Form
For demonstration purposes, the backend systems are ExpenseReportIn and ExpenseReportOut folders. Only expenses from the Marketing department are accepted. Messages from other departments appear as error messages in the ExpenseReportOut directory. Errors are prefixed with Error and non-errors are prefixed with Expense. Figure 4 presents a sample error message.
Figure 4: Sample Error Message
A user is allowed to edit and resubmit the error message within an hour of receiving it. The orchestration called ResubmitLogic handles the error message routing and resubmission process. Now that you know what the error message sample does, find out how it works.
Receiving Failed Messages
As previously stated, failed message routing is not on by default. You first must configure failed message routing on the port. Figure 5 shows the port configuration dialog.
Figure 5: Port Configuration Dialog
Once enabled, any processing failure in the port or routing failure from the port will create a message in the Messagebox coupled with ErrorMessage context information. As long as there are subscribers to the ErrorMessage, for the most part you will no longer see suspended messages for the receive port in the Messagebox.
Now that failed message routing is enabled, you must set up a subscriber for the ErrorMessage. As stated earlier, a subscriber can be an orchestration or a send port. The sample implements an orchestration subscriber.
As you can see in Figure 6, the orchestration is directly bound to the MessageBox in the port properties on the ResubmitLogic orchestration.
Figure 6: Port Properties
A filter also has been applied to the Receive_FailedMessage activation step in the orchestration so only ErrorMessages from the ReceiveExpenseReport port are sent to the orchestration (see Figure 7).
Figure 7: Properties for Receiving Failed Messages
Once the appropriate messages are received, the remainder of the orchestration adds additional data to the message and then manages the resubmission process.
The introduction discussed introducing human intervention into the error-handling process. Error expense reports can be resubmitted. The ResubmitLogic orchestration intercepts the error and manages the resubmission process.
First, ResubmitLogic adds the following two pieces of information before the error is routed to the ExpenseReportOut folder:
- Error message information: The existing message must be enriched with error message information extracted from the context information. Context information is not part of the message; it is attached to the message in the BizTalk Messagebox. Therefore, context information must be explicitly copied out of the message context to the message.
- Correlation ID: A correlation ID must be assigned. BizTalk will use the Correlation ID to route resubmitted messages to the correct running orchestration.
Next, BizTalk send ports add InfoPath processing instructions to the document as it leaves the send port. Processing instructions pointing to the InfoPath document’s template are stored inside every InfoPath document.
Ports are configured to use the XMLTransmit pipeline. The XMLTransmit pipeline can be configured to inject the processing instructions into the document as the document leaves the BizTalk send port. Figure 8 shows the XMLTransmit configuration dialog. Note the XmlAsmProcessingInstructions property.
Figure 8: XMLTransmit Configuration Dialog
Finally, to complete the resubmit, users can change data on the enriched error message and resubmit from inside InfoPath. Resubmissions are sent back to the ResubmitLogic orchestration. Figure 9 shows the resubmission portion of the orchestration.
Figure 9: Resubmission Portion of the Orchestration
Using the Correlation ID, the message is routed back to the correct orchestration. The orchestration creates a new expense submission on the ExpenseReportIn folder and then terminates.
Variations on a Theme
You can apply the ideas learned here to other scenarios. Instead of a set of folders or shares, imagine a SharePoint site that users can monitor to view and fix errors. Instead of using the file adapter, you can send error messages using the SharePoint adapter. The site can contain instructions and other information to supplement the InfoPath template.
In SharePoint lists, you can track comments and even initiate discussion threads. Web parts can host reports and other applications.
Users can subscribe to changing contents on the document libraries; if errors are infrequent, they can be notified via SharePoint document library change notifications.
Also from SharePoint, you can initiate separate human workflows to handle more complicated errors. For example, many users may be required to sign off on an error before it is applied.
Human Intervention for Error Handling
Proper error handling in your integration project can be the difference between success and failure. Human intervention error handling often requires business knowledge as well as the right tools. In BizTalk, InfoPath and failed message routing can be the foundation for building these tools. Failed message routing provides the mechanism for trapping and routing the error. InfoPath provides the human interface for correcting the error. The error-handling sample in the BizTalk SDK provides a good example of how to configure failed message routing and use InfoPath.
Download the Code
Download the sample for this article.
About the Author
Jeffrey Juday is a software developer with Crowe Chizek in South Bend, Indiana. He has been developing software with Microsoft tools for more than 12 years in a variety of industries. Jeff currently builds solutions using BizTalk 2004, ASP.NET, SharePoint, and SQL Server 2000. You can reach Jeff at [email protected].