How do I Handle Faults?
A fault is an error or failure. When a fault occurs, fault handling provides a means of error handling, including backing out the unsuccessful or incomplete work of an activity by transferring control to the fault handler that you defined.
You can add fault handlers to the top-level process or to an Invoke activity or Scope within the process.
If the fault handler is not at the process level, you must add an Exit activity after each Reply within the fault handler.
The fault handler is triggered when the fault occurs. The fault can occur at any time, after certain activities have completed successfully, in the middle of an activity, or before certain other activities have had a chance to run.
You can create fault handlers for three different types of faults:
Service faults—these faults occur when a third-party Web service operation cannot successfully complete. The name and structure of the fault is defined in the WSDL fault declarations.
- User-defined faults—these are faults that you define to do your own error handling. You can throw and catch these faults within your process.
- Standard BPEL faults—these faults illustrate a problem with the process. These faults are defined in the BPEL specification. For a list see Standard BPEL Faults.
You can throw faults and you can catch faults. Faults can happen at any time and you can catch them using fault handlers on Invoke activities, Scopes, or at the process level.
To add a fault handler to your process
In the BPEL Editor, decide where you want to place the fault handler within the process, right-click and select Add Fault Handler. You can add fault handlers to Invoke activities, Scopes, or at the process level.
The fault handler template displays which you can use to configure the fault handler.
To configure the fault handler, click the Catch element in the fault handler template.
You can now interact with the Catch Properties view.
Select the Fault Type for the fault you are going to catch: Service, User-defined, or Standard BPEL. In the Web Service Explorer, which you use to test your service, it is easy to determine the fault you are working with by forcing your service to fail. This is usually done by supplying invalid input to the process. In the Status pane, note the fault type.
The Fault Name drop down list provides a complete list of the faults that can originate from the current process or scope. In the example in Step 3 it is a-user fault-, but it can be any fault available from the drop down list.
The variable name is the name of the local variable that is automatically created and that contains the fault information. This is useful to extract information about the fault that occurred, which you will walk through in the following steps. The structure of the fault shows you want the fault looks like.
The next step is to make sure you can return output to the user. Depending on your own circumstances this process will vary. In many cases you will want to add your own logic by means of an Assign and copy rule. These instructions assume that scenario.
- Delete the default handler from the fault handler in the process diagram and drag an Assign activity from the Palette.
- Click to open the Create Copy Rule dialog box.
- You now want to copy from the user fault to the output. In the From panel expand the fault node, expand the fault parameters and select the Description element. You can copy the description of the fault to the output variable.
- In the To panel select the output variable since you want to copy the fault description to the output. Click OK.
To send the response back to the user, add a Reply activity and configure it for an output using the Quick Pick panel in the Properties view.
You can add other catches for other faults in the service by following the same process.
Deploy to the Process Server to test using the Web Services Explorer.
You can throw and catch your own faults by using the Throw and Catch activities from the Palette. This procedure is very similar to the one for catching faults.
From the palette, drag a Throw activity to the process diagram wherever you want to throw a fault. This is just a sample illustration.
The Properties view for the Throw activity is very similar to the one described in the Catching Faults section and you interact with it similarly.
Choose your own fault name and optionally click Browse to create your own fault variable. The fault variable defines the structure of the fault. This is optional. If you decide to do this you can use the Schema Editor to define the structure of the variable, create a highly specific error, throw it, and later catch it.
Create a fault handler to catch your fault. As in step 2 above, add a fault handler and define the fault handling logic using the copy rule dialog box.