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.
Types of Web Service Faults
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.
Scope Step
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.
FaultHandler Section
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:
- You can right-click a Service step in a scope and select Add Catch Branches to Scope to add a catch branch for each fault the step can throw. The SBM Orchestration Engine selects the appropriate catch branch when the step throws a fault.
- ServiceFlowFault is the only fault that a
Throw step can throw. The catch branch with
ServiceFlowFault selected as the
Fault name on the
General tab of its Property Editor is selected
for
Throw steps that have a
Fault message displayed on the
General tab of the step Property Editor.
Important: If there are several Throw steps within the same Scope, each one takes this branch, even if they have different Fault message values.
- If no catch or catch all branches are selected, the fault is not caught and is thrown back to the immediately enclosing scope.
CompensationHandler Section
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.
Throw 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?
- Notify a user that the synchronous orchestration workflow encountered a problem and cannot continue.
- Together with a fault handler, notify a user that the invocation of a Web service within this orchestration workflow returned a SOAP fault.
- Immediately stop the execution of the scope that encloses the step.
- Log the contents of the fault that is thrown by the Throw step and display it in the Log Viewer.
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.
Summary
- The only fault that can be thrown by a Throw step is ServiceFlowFault.
- The content of the FaultString data element of the ServiceFlowFault is shown to users if the fault is thrown within a synchronous orchestration workflow.
- The content of the ServiceFlowFault is logged when the fault is thrown and can be used during debugging.
- After a Throw step is executed, the activity in the next enclosing scope is stopped.
Compensate Step
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
- If you select the Default Scope, the SBM Orchestration Engine checks all immediately enclosed scopes that completed successfully to determine if they have compensation handlers defined in them. If multiple scopes have completed successfully and all have compensation handlers, these scopes are called one by one in reverse order, that is, the one that completed last is called first. For example, scope "Scope" immediately encloses scopes "Scope2" and "Scope3." If there is a Compensate step in the CompensationHandler of scope "Scope," the SBM Orchestration Engine runs the compensation handlers in scope "Scope3" and then in "Scope2," if they both completed successfully. To change the order in which the scopes are called, you can place more than one Compensate step in a CompensationHandler section.
- If you select a specific scope, the BPEL engine only checks that scope to determine if it completed successfully and if it has a compensation handler defined in it. If it completed successfully and has a compensation handler, the compensation handler is called. The compensation handler in this scope can then call other scopes for compensation if it designed to do so.
Figure 1. Enclosed Scopes
