Using the AquaLogic Service Bus Console

Proxy Services: Error Handlers

This section includes the following topics:

Error Messages and Handling

This section includes the following topics:

Error Handlers

BEA AquaLogic Service Bus enables you to configure your system to format and return error messages.

Errors can occur during Message Flow processing for various reasons. For example, security errors occur if a username is not correctly validated or authorized; transformation errors occur if AquaLogic Service Bus is unable to successfully transform or validate a message; a routing error is raised if a routing service is unavailable, and so on. Typically, these errors originate from a specific stage, route node or from the proxy service, as this is where most of the Message Flow logic is implemented.

AquaLogic Service Bus provides a mechanism to handle these errors by enabling you to define error handlers. An error handler is a pipeline that allows you to perform various actions such as logging, transformation, and publishing to handle errors appropriately.

If an error occurs within a stage a sequence of steps are executed. This sequence of steps constitutes an error pipeline for that stage.

Nested Error Handlers

You can configure an error handler for the entire Message Flow as well as for every pipeline and stage within the Message Flow. You may also configure error handlers for route nodes but not for branch nodes.

When an error occurs, it is handled by the inner-most encompassing error handler. For example, a stage's error handler handles a transformation error if it occurs while executing the assign action in that stage. If there is no error handler configured for the stage, it is handled by the next level error handler, which is that of the pipeline that contains the transformation stage. If that error handler does not exist, it is then handled by the Message Flow-level error handler. If that fails, then a default system-level error handler processes the error.

The next level error handler for uncaught errors that occur in a route node is the Message Flow-level handler. Thus, unlike stage errors which can be handled at 3 levels by user-configured handlers, Message Flow errors can only be caught by at most 2 levels of user-configured handlers.

Every component—stage, pipeline or Message Flow—can have at most 1 error handler. Therefore, only 1 Message Flow-level error handler is used to process any error that occurs during either request or response processing (that is not handled at a lower level by a pipeline or stage error handler). Since the inbound binding layer is not associated with any particular stage or pipeline, errors that occur in the binding layer are always handled by the Message Flow-level error handler. Outbound binding layer errors may occur in several places, depending on what entity is performing communication. For example, binding layer errors that occur during routing can be caught by the routing node's error handler. Similarly, binding layer errors that occur during a publish operation in a publish stage can be caught by the stage-level error handler.

Empty Error Handlers

An empty or unconfigured error handler is identical to not having an error handler. For example, if the stage-level error handler was created but never configured, then the error bubbles-up to the next level handler.

Error Handler Actions

When an error handler processes an error, it can finish with one of two actions:

Table 18-1 Error Handler Actions

Error Actions	Description
Reply	If you assign this action, an error response is immediately created for the proxy service client. All further Message Flow processing stops and a response message is sent based on the message-related context variables. In this instance, you can configure the error handler to send a simple reply to the proxy service or a more detailed reply stating that an error occurred. The difference between HTTP reply with success and reply with failure is as follows: Reply with success sends status code 200 and $body Reply with failure status sends status code 500 and $body
Resume	When this action is included in a message flow, message flow processing continues as though no error has occurred. Processing continues after the node or stage in which the error handler is configured. You may need to configure the error handler with compensating logic to set the context variables and message state to correspond with the variable and message state expected by subsequent message flow logic. Configure the compensating logic prior to the Resume action.

Error Actions

Description

If you assign this action, an error response is immediately created for the proxy service client. All further Message Flow processing stops and a response message is sent based on the message-related context variables. In this instance, you can configure the error handler to send a simple reply to the proxy service or a more detailed reply stating that an error occurred.

The difference between HTTP reply with success and reply with failure is as follows:

Reply with success sends status code 200 and $body

Reply with failure status sends status code 500 and $body

Resume

When this action is included in a message flow, message flow processing continues as though no error has occurred. Processing continues after the node or stage in which the error handler is configured. You may need to configure the error handler with compensating logic to set the context variables and message state to correspond with the variable and message state expected by subsequent message flow logic. Configure the compensating logic prior to the Resume action.

If neither the Reply nor the Resume action is initiated, the error is rethrown. In this case, the error is pushed forward and handled by the next level error handler. Unless otherwise specified, the rethrow action is the default action of an error handler.

To learn how Message Flow chooses among these actions, see Error Handler Configuration.

Error Handler Configuration

Since an error handler is another pipeline, it is configured like any other pipeline. For example, the Publish action may be used to send error notifications to other services, the Assign action may be used to modify the context variables, and so on. Some actions, however, are not allowed to appear in an error handler.

In addition to the standard context variables, there is an additional context variable available to an error handler—the $fault variable. The $fault variable contains information about any error that occurs during Message Flow processing. When an error occurs, this variable is populated with information about the error, prior to the error-handler being invoked. The $fault variable is only ever defined within error handlers. It is never defined within a simple request and response pipeline. This is the key difference between an error pipeline and any other pipeline.

There are four core elements within the $fault variable:

Table 18-2 Error Handler Configuration

Element	Description
errorCode	Holds an error code as a string value
Reason	Contains a brief textual description of the error
Details	Contains arbitrary XML content about the error
Location	Identifies the pipeline and the stage where the error occurred

You can modify the $fault variable; however it is only relevant inside an error handler.

Adding Error Handling for the Proxy Service

The Edit Message Flow page enables you to add error handling for the proxy service. You can configure error handling at the Message Flow, pipeline, route node, and stage level. To learn more, see Error Messages and Handling.

To Add Error Handling for a Proxy Service

If you have not already done so, from the left navigation pane, under Change Center, click Create to create a new session for making changes to the current configuration. To learn more, see Using the Change Center.

On the Summary of Proxy Services page, click the Edit Message Flow icon for the appropriate proxy service. Alternatively, if you are in the Project Explorer module, click the Edit Message Flow icon for the appropriate proxy service in the list of resources for a selected project or folder.

The Edit Message Flow page is displayed for the proxy service you selected. The page includes the following functionality:

A proxy service icon
The name of the proxy service
A pipeline pair node icon and name if you have already added a pipeline pair node
In the left navigation pane, a map of the Message Flow, which enables you to link to the pages associated with the various objects in the Message Flow.

Click the Proxy Service icon, then click Add Service Error Handler. The Edit Error Handler page is displayed, which includes an Error Handler icon.

Click the Error Handler icon, then click Add Stage. The Stage icon is displayed.

Click the Stage icon, click Edit, then click Stage. The Edit Stage Configuration page is displayed.

To add an action, click Add an Action, then select the action you want to add.

Since an error handler is another pipeline, it is configured like any other pipeline. For example, the Publish action may be used to send error notifications to other services, the Assign action may be used to modify the context variables, and so on. To learn more about the type of action you want to add, see the appropriate procedure in Adding an Action. There is no restriction on what actions may be chained together.
In addition, three commonly-used error actions are Raise Error, Reply, and Resume. To learn more about these actions, see Error Handler Actions in Error Messages and Handling.
When you have finished adding actions, continue to the next step.

Do one of the following:

To save the actions, click Save. The Edit Error Handler page is displayed.
To disregard changes and return to the Edit Error Handler page, click Cancel.
To clear any unsaved edits and remain on the Edit Stage Configuration page, click Clear.

When you have saved the actions, do one of the following:

Table 18-3 Adding Proxy Service Error Handling

To...	Complete This Step...
Continue adding actions to configure the error handler	Click the Stage icon, click Edit, then click Stage.
Edit the stage name and description	Click the Stage icon, click Edit, then click Name and Description.
Add another stage	Click the Error Handler or Stage icon, then click Add Stage.
Save the updates and return to the Edit Message Flow page	Click Save.
Disregard changes and return to the Edit Message Flow page	Click Cancel.
Clear the changes and remain on the Edit Error Handler page	Click Clear.
Discard your changes and exit the message flow	Click Cancel All. When you confirm that you want to exit the Message Flow, the Summary of Proxy Services page is displayed if you initially clicked the Edit Message Flow icon for the proxy service on that page or the Project View or Folder View pages are displayed if you clicked the Edit Message Flow icon for the proxy service on those pages.

Note: When you click Save, the Message Flow is updated in the current session. When you have finished making changes to this configuration, from the left navigation pane, click Activate under Change Center. The session ends and the core configuration is updated. Alternatively, click Discard at any time during the session to delete the changes you have made so far in the current session.

Adding Pipeline Error Handling

The Edit Message Flow page enables you to add error handling for a pipeline. You can configure error handling at the Message Flow, pipeline, route node, and stage level. To learn more, see Error Messages and Handling.

Note: You must create a pipeline pair node before you can add a pipeline error handler. To learn more, see Adding a Pipeline Pair Node.

To Add Error Handling for a Pipeline

The Edit Message Flow page is displayed for the proxy service you selected.

Expand an existing pipeline pair node to view the pipeline pair, which consists of request and response pipelines.

Click the pipeline to which you want to add error handling, then click Add Pipeline Error Handler. The Edit Error Handler page is displayed.

Click the Error Handler icon, then click Add Stage. The Stage icon is displayed.

Click the Stage icon, click Edit, then click Stage. The Edit Stage Configuration page is displayed.

To add an action, click Add an Action, then select the action you want to add.

Since an error handler is another pipeline, it is configured like any other pipeline. For example, the Publish action may be used to send error notifications to other services, the Assign action may be used to modify the context variables, and so on. To learn more about the type of action you want to add, see the appropriate procedure in Adding an Action. There is no restriction on what actions may be chained together.
In addition, three commonly-used error actions are Raise Error, Reply, and Resume. To learn more about these actions, see Error Handler Actions in Error Messages and Handling.
When you have finished adding actions, continue to the next step.

Do one of the following:

To save the actions, click Save. The Edit Error Handler page is displayed.
To disregard changes and return to the Edit Error Handler page, click Cancel.
To clear any unsaved edits and remain on the Edit Stage Configuration page, click Clear.

When you have saved the actions, do one of the following:

Table 18-4 Adding Pipeline Error Handling

To...	Complete This Step...
Continue adding actions to configure the error handler	Click the Stage icon, click Edit, then click Stage.
Edit the stage name and description	Click the Stage icon, click Edit, then click Name and Description.
Add another stage	Click the Error Handler or Stage icon, then click Add Stage.
Save the updates and return to the Edit Message Flow page	Click Save.
Disregard changes and return to the Edit Message Flow page	Click Cancel.
Clear the changes and remain on the Edit Error Handler page	Click Clear.
Discard your changes and exit the message flow	Click Cancel All. When you confirm that you want to exit the Message Flow, the Summary of Proxy Services page is displayed if you initially clicked the Edit Message Flow icon for the proxy service on that page or the Project View or Folder View pages are displayed if you clicked the Edit Message Flow icon for the proxy service on those pages.

Adding Stage Error Handling

The Edit Message Flow page enables you to add error handling for a stage. You can configure error handling at the Message Flow, pipeline, route node, and stage level. To learn more, see Error Messages and Handling.

Note: You must create a stage before you can add a stage error handler. To learn more, see Adding a Stage.

To Add Error Handling for a Stage

The Edit Message Flow page is displayed for the proxy service you selected.

Expand an existing pipeline pair node to view the pipeline pair, which consists of request and response pipelines. If you have previously added stages, the Stage icons are also displayed.

Click the Stage icon for the stage you want to edit, click Add, then click Add Stage Error Handler. The Edit Error Handler page is displayed.

Click the Error Handler icon, then click Add Stage. The Stage icon is displayed.

Click the Stage icon, click Edit, then click Stage. The Edit Stage Configuration page is displayed.

To add an action, click Add an Action, then select the action you want to add.

Since an error handler is another pipeline, it is configured like any other pipeline. For example, the Publish action may be used to send error notifications to other services, the Assign action may be used to modify the context variables, and so on. To learn more about the type of action you want to add, see the appropriate procedure in Adding an Action. There is no restriction on what actions may be chained together.
In addition, three commonly-used error actions are Raise Error, Reply, and Resume. To learn more about these actions, see Error Handler Actions in Error Messages and Handling.
When you have finished adding actions, continue to the next step.

Do one of the following:

To save the actions, click Save. The Edit Error Handler page is displayed.
To disregard changes and return to the Edit Error Handler page, click Cancel.
To clear any unsaved edits and remain on the Edit Stage Configuration page, click Clear.

When you have saved the actions, do one of the following:

Table 18-5 Adding Stage Error Handling

To...	Complete This Step...
Continue adding actions to configure the error handler	Click the Stage icon, click Edit, then click Stage.
Edit the stage name and description	Click the Stage icon, click Edit, then click Name and Description.
Add another stage	Click the Error Handler or Stage icon, then click Add Stage.
Save the updates and return to the Edit Message Flow page	Click Save.
Disregard changes and return to the Edit Message Flow page	Click Cancel.
Clear the changes and remain on the Edit Error Handler page	Click Clear.
Discard your changes and exit the message flow	Click Cancel All. When you confirm that you want to exit the Message Flow, the Summary of Proxy Services page is displayed if you initially clicked the Edit Message Flow icon for the proxy service on that page or the Project View or Folder View pages are displayed if you clicked the Edit Message Flow icon for the proxy service on those pages.

Adding Error Handling for the Route Node

The Edit Message Flow page enables you to add error handling for a route node. You can configure error handling at the Message Flow, pipeline, route node, and stage level. To learn more, see Error Messages and Handling.

Note: You must create a route node before you can add a route node error handler. To learn more, see Adding a Route Node.

To Add Error Handling for a Route Node

The Edit Message Flow page is displayed for the proxy service you selected.

Click the Route Node icon, then click Add Error Handler. The Edit Error Handler page is displayed.

Click the Error Handler icon, then click Add Stage. The Stage icon is displayed.

Click the Stage icon, click Edit, then click Stage. The Edit Stage Configuration page is displayed.

To add an action, click Add an Action, then select the action you want to add.

Since an error handler is another pipeline, it is configured like any other pipeline. For example, the Publish action may be used to send error notifications to other services, the Assign action may be used to modify the context variables, and so on. To learn more about the type of action you want to add, see the appropriate procedure in Adding an Action. There is no restriction on what actions may be chained together.
In addition, three commonly-used error actions are Raise Error, Reply, and Resume. To learn more about these actions, see Error Handler Actions in Error Messages and Handling.
When you have finished adding actions, continue to the next step.

Do one of the following:

To save the actions, click Save. The Edit Error Handler page is displayed.
To disregard changes and return to the Edit Error Handler page, click Cancel.
To clear any unsaved edits and remain on the Edit Stage Configuration page, click Clear.

When you have saved the actions, do one of the following:

Table 18-6 Adding Route Node Error Handling

To...	Complete This Step...
Continue adding actions to configure the error handler	Click the Stage icon, click Edit, then click Stage.
Edit the stage name and description	Click the Stage icon, click Edit, then click Name and Description.
Add another stage	Click the Error Handler or Stage icon, then click Add Stage.
Save the updates and return to the Edit Message Flow page	Click Save.
Disregard changes and return to the Edit Message Flow page	Click Cancel.
Clear the changes and remain on the Edit Error Handler page	Click Clear.
Discard your changes and exit the message flow	Click Cancel All. When you confirm that you want to exit the Message Flow, the Summary of Proxy Services page is displayed if you initially clicked the Edit Message Flow icon for the proxy service on that page or the Project View or Folder View pages are displayed if you clicked the Edit Message Flow icon for the proxy service on those pages.

Viewing and Changing an Error Handler

The Edit Message Flow page enables you to view and change error handlers. You can configure error handling at the Message Flow, pipeline, route node, and stage level. To learn more, see Error Messages and Handling.

To View and Change an Error Handler

The Edit Message Flow page is displayed for the proxy service you selected.

Do one of the following:

Table 18-7 Viewing and Changing the Error Handler

To...	Complete This Step...
View and change the error handler for the proxy service	Click the Proxy Service icon, then click Edit Service Error Handler. The Edit Error Handler page is displayed. To learn more, see Adding Error Handling for the Proxy Service.
View and change the pipeline error handler	Click the appropriate Pipeline Pair icon, then click Edit Pipeline Error Handler. The Edit Error Handler page is displayed. To learn more, see Adding Pipeline Error Handling.
View and change the route node error handler	Click the Route Node icon, click Edit, then click Error Handler. The Edit Error Handler page is displayed. To learn more, see Adding Error Handling for the Route Node.
View and change the stage error handler	Click the appropriate Stage icon, click Edit, then Stage Error Handler. The Edit Error Handler page is displayed. To learn more, see Adding Stage Error Handling.

Deleting an Error Handler

The Edit Message Flow page enables you to delete existing error handlers. You can configure error handling at the Message Flow, pipeline, route node, and stage level. To learn more, see Error Messages and Handling.

To Delete an Error Handler

The Edit Message Flow page is displayed for the proxy service you selected.

Do one of the following:

Table 18-8 Deleting the Error Handler

To...	Complete This Step...
Delete the error handler for the proxy service	Click the Proxy Service icon, then click Delete Service Error Handler. The service error handler is deleted.
Delete the pipeline error handler	Click the appropriate Pipeline Pair icon, then click Delete Pipeline Error Handler. The pipeline error handler is deleted.
Delete the route node error handler	Click the Route Node icon, click Edit, then click Error Handler. The route node error handler is deleted.
Delete the stage error handler	Click the appropriate Stage icon, click Edit, then Stage Error Handler. The stage error handler is deleted.

Note: When you click Delete, the Message Flow is updated in the current session. When you have finished making changes to this configuration, from the left navigation pane, click Activate under Change Center. The session ends and the core configuration is updated. Alternatively, click Discard at any time during the session to delete the changes you have made so far in the current session.

Proxy Services: Error Handlers

Error Messages and Handling

Error Handlers

Nested Error Handlers

Empty Error Handlers

Error Handler Actions

Error Handler Configuration

Related Topics

Adding Error Handling for the Proxy Service

To Add Error Handling for a Proxy Service

Related Topics

Adding Pipeline Error Handling

To Add Error Handling for a Pipeline

Related Topics

Adding Stage Error Handling

To Add Error Handling for a Stage

Related Topics

Adding Error Handling for the Route Node

To Add Error Handling for a Route Node

Related Topics

Viewing and Changing an Error Handler

To View and Change an Error Handler

Related Topics

Deleting an Error Handler

To Delete an Error Handler

Related Topics