BizTalk 2010 Recipes : Orchestrations - Catching Exceptions Consistently

1. Problem

You want to be able to catch all exceptions in the same way and be able to handle retries automatically with a configurable delay. You also want to be able to resubmit documents that have failed without losing context to what step in the orchestration flow was last executed.

2. Solution

The ExceptionHandlerPatternDemo project shows the use of the pattern, with a single Business Flow orchestration calling two different paths in a single Task Processing orchestration. Neither the Business Flow orchestration (SAMPLEMainBusinessFlow.odx) nor the Task Processing orchestration (SAMPLEExternalComponentCall.odx) are required in a true implementation. They are provided for demonstration purposes only. All of the files in the Common Schemas project and all of the files in the Exception Handler Buffer project are required, and need no modifications (aside from possible namespace modifications) to be used in any other solution.

The SAMPLEMainBusinessFlow orchestration demonstrates calling the other orchestrations with multiple input parameters (as demonstrated in the first Task Request grouping) and with an XML document that needs to be mapped (as demonstrated in the second Task Request grouping). Use the following steps to deploy and test the solution.

3. How It Works

Based on a publish/subscribe architecture, the Exception Handler pattern can be used to buffer calls to components that may throw exceptions from the actual business flow of a process. The Exception Handler buffer allows for a common mechanism to catch, process, and retry exceptions (including notification to an administrator) that can be reused across multiple solutions. Figure 1 shows the high-level architecture of a request, and Figure 2 shows the high-level architecture of a response.

The orchestrations are built in such a way that the business workflow is separate from the actual calls to external tasks. The only orchestration that references anything besides ports that are directly bound to the MessageBox are the Task Processing orchestrations. So, too, these orchestrations are the only ones that will throw exceptions that need to be handled in a common way.

Any time an exception is thrown for any reason (such as a call to an external assembly throws an error, a web service is down, a database cannot be connected to, and so on), the Task Processing orchestration will catch the error, wrap the error information in a message, and return the message back to the Exception Handler orchestration. The Exception Handler orchestration will then decide whether to retry the call to the task (for system exceptions)—for example, if a database cannot be connected to, the orchestration will delay for a specified period of time and then retry—or simply notify an administrator and wait for a response. The response back from an administrator could indicate that the call to the task should be retried or that the entire process should be cancelled.

The Exception Handler pattern can be used in a variety of scenarios, with the following benefits:

• It offers configurable automatic retries of system exceptions.

• An administrator is notified (via any type of BTS adapter) for business rule exceptions and after a maximum number of automatic retries of system exceptions.

• It allows multiple unrelated orchestrations to publish to a single version of the Exception Handler orchestration.

• There are no uncaught or unhandled exceptions.

• No messages end up suspended.

• It offers complete visibility into the life cycle of an orchestration.

Figure 1. High-level architecture of the request

Figure 2. High-level architecture of the response

The orchestrations communicate with one another through the publish/subscribe model, meaning that the publishing orchestration drops a message on the BizTalk MessageBox to which the subscribing orchestration is subscribing. The following sections describe these schemas and how they are used.

3.1. Exception Handler Buffer Call Request Schema

This schema is published by the Business Flow orchestration(s) and subscribed to by the Exception Handler Buffer orchestration. It contains all of the data needed to call a task and all of the configurable information needed by the exception handler to process and retry exceptions (such as maximum number of retries, delay between retries, and so on). Table 1 shows the schema definition.

3.2. Exception Handler Buffer Call Response Schema

This schema is published by the Exception Handler orchestration and subscribed to by the Main Business Flow orchestration(s). It contains the output information needed by the Main Business Flow to determine what (if any) the result of the Task Processing orchestration call may have been. Table 2 shows the schema definition.

3.3. Task Processing Logic Call Schema

This schema is published by the Exception Handler orchestration and is subscribed to by the Task Processing orchestration(s). All Task Processing orchestration instances subscribe to this schema type. Use a filter expression on the individual Task Processing orchestration's initial Receive shape to indicate which instance to kick off (based on the OrchestrationFilter parameter). Table 3 shows the schema definition.

3.4. Task Processing Logic Response Schema

This schema is published by the Task Processing Logic orchestration(s) and subscribed to by the Exception Handler Buffer orchestration. It contains the output information needed by the Main Business Flow to determine what (if any) the result of the Task Processing orchestration call may have been and by the Exception Handler Buffer orchestration to determine what exceptions may be present and if the call needs to be retried (based on the presence of exceptions). Table 4 shows the schema definition.

3.5. Error To Administrator Schema

This schema is published by the Exception Handler orchestration and is published to an administrator. This may be as simple as writing to a file, or it could be set up to write to a database or any other protocol desired. The Error To Administrator schema contains all of the information that an administrator would need to understand what error was thrown. Once the administrator is ready to resubmit the document to the process, the same schema type is resubmitted. Table 5 shows the schema definition.