SBM Orchestration Guide → Orchestration Procedures → Using the Scope, Throw, and Compensate Steps to Handle Faults From Web Services
The Scope, Throw, and Compensate steps in SBM Composer graphically represent BPEL fault-handling elements. You use these steps to handle Web service faults. This section provides a brief overview of BPEL fault handling and how it is implemented in SBM Composer.
The two types of Web service faults are "named" faults and "generic" faults. A named fault is associated with a specific fault situation, such as entering an incorrectly formatted user name or attempting to withdraw money from a bank account that is inactive. A generic fault is returned by a Web service if the service does not specify any named faults. Web services return faults in SOAP messages that contain SOAP faults. (See About SOAP Messages.)
If a Web service fault is not handled, or caught, it can stop the entire business process. Unhandled Web service faults are the most common causes of orchestration workflow failures. This section explains the various ways you can use the fault-handling components in SBM Composer to keep your business processes flowing smoothly.
The Scope step lets you group related activities. It contains a FaultHandler section and a CompensationHandler section. Scopes can be nested, that is, one scope can enclose another scope. Orchestration workflows are contained within implicit, or global, scopes.
If a Web service inside of a scope generates a SOAP fault or if an internal BPEL fault occurs, the SBM Orchestration Engine checks whether a fault handler is defined for the scope. The catch branch within the fault handler "catches" the faults so they can be handled. The fault handler can contain an unlimited number of catch branches.
If the SBM Orchestration Engine finds a fault handler, it selects the catch branch with the value that best matches the fault according to the following rules:
The SBM Orchestration Engine invokes compensation handlers when there is a Compensate step in the enclosing scope. You can use any steps in the Step Palette to create a compensation handler. For an example, see Using the Compensate Step.
During the execution of an orchestration workflow, errors might prevent the workflow from completing. For example, suppose you design an orchestration workflow that transfers money between two accounts by invoking a few Web services. However, the first Web service call returns an "invalid account number" fault.
The orchestration workflow stops, unless it contains some logic in the fault handler of the scope that encloses the Web service. For example, you might want to inform the user that he or she entered an invalid account number. The best way to do this by using the Throw step to generate a custom error message such as "The account number you entered is not valid. Please try again."
Orchestration Workflows as Web Services
An orchestration workflow itself is invoked as a Web service, although this Web service can only be accessed by the SBM Application Engine. An orchestration workflow is invoked in one of two modes: Request Only (EventNotice) or Request and Respond (EventNoticeWithReply). EventNotice is used when an asynchronous orchestration workflow is invoked, and EventNoticeWithReply is used when a synchronous orchestration workflow is invoked.
A Web service could respond with a SOAP fault if something went wrong during its execution. For each orchestration workflow that is invoked, a WSDL file is generated for its corresponding Web service.
The following sample code is a EventNoticeWithReply Web service operation that is defined in a WSDL file. It shows that the Web service for the orchestration workflow can return a SOAP fault named ServiceFlowFault. All orchestration workflows can return, or throw, a ServiceFlowFault. In fact, this is the only SOAP fault that they can throw.
<wsdl:operation name="EventNoticeWithReply"> <wsdl:input message="tns:XxxxxEventNoticeWithReply" /> <wsdl:output message="tns:XxxxxEventNoticeWithReplyResponse" /> <wsdl:fault name="ServiceFlowFault" message="tns:ServiceFlowFault" /> </wsdl:operation>
Why Use a Throw Step?
If a Web service that is invoked within a synchronous orchestration workflow receives a fault as a reply, the user of your process app does not see the fault message, unless you provided a fault handler to catch the fault. Instead, he or she will see the following generic error message: "An error occurred during the execution of the synchronous orchestration workflow." If you want to display the fault message to the user, enclose the Web service invocation within a scope, catch the fault that is thrown by the Web service, and throw a ServiceFlowFault using a Throw step. See Using the Throw Step for more information.
If a Web service is invoked within an asynchronous orchestration workflow, you cannot notify a user, as previously described in steps 1 and 2, because asynchronous orchestration workflows do not return anything to the caller, which is the SBM Application Engine. However, an asynchronous orchestration workflow can accomplish the tasks described in items 3 and 4.
How to Use the Throw Step
The procedure for using a Throw step is described in Using the Throw Step.
If a Throw step is not enclosed within a scope with a fault handler, the whole workflow is stopped after that step is executed. In addition, the content of its FaultString data element is displayed to users if the orchestration workflow is synchronous.
If a Throw step is enclosed within a scope that has a fault handler, the fault handler can catch the ServiceFlowFault that is thrown by the Throw step. To do this, you can use either a Catch branch for a named fault or the CatchAll branch. After the ServiceFlowFault is caught, you could use another Throw step to throw a new ServiceFlowFault to the SBM Application Engine. The orchestration workflow that you create in Using the Throw Step demonstrates how to do this.
During the execution of an orchestration workflow, you might need to reverse, or compensate, an activity that already completed. For example, say you design an orchestration workflow that transfers money between two accounts by invoking a few Web services. One Web service call in the orchestration workflow withdraws funds from the first account and records the transaction. Another Web service call checks the status of the second account and returns an "inactive account" fault. A third Web service call pays back the funds to the first account because the second account is inactive.
An inner scope contains the Web service that withdraws funds. This scope has a CompensationHandler that calls the Web service that pays back the funds. An outer scope encloses the inner scope. The outer scope contains the Web service that checks whether the second account is valid. The outer scope also contains a FaultHandler, in which a proper Catch branch contains the Compensate step. When the "inactive account" fault is caught, the Compensate step is executed.
Configuring a Compensate Step
Figure 1. Enclosed Scopes
Copyright © 2007–2016 Serena Software, Inc. All rights reserved.