Mapping HTTP Error Responses
This chapter describes how the ACE XML Gateway deals with service errors. It covers these topics:
•Setting General SOAP Fault Options
•Configuring Global Exception Settings
•Configuring Service-Specific Exception Behavior
An HTTP error response, or exception, is a message sent to the client to indicate that a request could not be processed as expected. The exception can be caused by a variety of conditions, including insufficient credentials in the request, a malformed request, an unavailable service, and many more. In general, such errors are defined as part of the protocol specification.
From the perspective of the ACE XML Gateway, an exception is generated in one of two ways:
•internally, by the ACE XML Gateway itself
•externally, which are generated remotely, usually by the back-end server or network
Since it mediates between service consumers and providers that use different protocols, the ACE XML Gateway must similarly be able to mediate from exceptions of one format to another. The ACE XML Gateway policy defines a default mapping between exception types for all protocols it supports, for example, from SOAP to plain HTTP or from HTTP to MQSeries.
Even for clients and services that use the same protocol, however, the exception mapping performed by the ACE XML Gateway serves to normalize the exceptions received by clients.
In some cases, you may want to modify the default exception mappings. Doing so can improve security (by hiding details of the backend system) and simplify exception handling for the client.
Besides changing default exception mappings, you can specify the following advanced features for certain types of exceptions:
•Remote exception pass through, in which the exception message is not mapped or otherwise modified at the ACE XML Gateway.
•Response processing on the exception. For a service-specific mapping, you can have a remotely generated response message processed as a response. Otherwise, an error response circumvents the processing and validation specifications configured for the response of a service. With this option, you can access the exception as a response, applying, for example, an XSLT to the exception message.
The following sections provide more information on these options.
Setting General SOAP Fault Options
Apart from exception mappings, you can configure several other aspects of exception handling at the ACE XML Gateway, namely the namespace settings for SOAP faults and email notifications of fault events.
Configuring Namespace Settings for SOAP Faults
A typical SOAP fault message from the Gateway appears as follows:
Example 22-1 SOAP Fault
<det:detailmessage>Forbidden. You are not allowed
to access that resource.</det:detailmessage>
By default, the ACE XML Gateway generates SOAP Faults in which the children elements of the
Fault element are not qualified with a SOAP namespace. Unqualified
Fault elements comply with the Web Services-Interoperability (WS-I) specification.
You can optionally have the ACE XML Gateway generate
Fault elements that are qualified. To configure these namespace settings, access the System Management > Gateway Settings page and modify the SOAP XML Namespace Configuration settings.
Settings applicable to how SOAP faults are generated include:
•SOAP fault detail entry name. The name used for the element that is the first child of the
detail element in the SOAP fault,
detailmessage by default.
•SOAP fault detail entry namespace. The namespace for the
detail element. By default, the
Detail element is qualified by the namespace: http://reactivity.com/
This should be changed to a namespace appropriate for your case.
•Use unqualified SOAP fault child elements. Excludes SOAP namespace prefixes from child elements of the
fault element. For WS-I compatibility, such elements must not have a namespace prefix. By default, this option is enabled. You can have the ACE XML Gateway add a prefix by disabling this option.
Configuring Exception Notification Email Address
The ACE XML Gateway can be configured to send an email notification when an exception occurs in the processing of a service request. You can enable exception notifications by virtual service, so that some types of service traffic generate error notifications while others do not.
A notification identifies the message affected by the error and indicates the reason for the error. Messages are identified by message GUIDs, the globally unique identifier for messages in the system. Figure 22-1 shows a sample error notification.
Figure 22-1 Exception notification
To enable email notification of exceptions:
Step 1 Find the Exception Notifications section in the ACE XML Gateway Settings page.
Step 2 Configure the controls in the Exception Notifications section as follows:
a. In the Send e-mail for the first exception notification and every field, type an interval to specify the number of exceptions that occur between notifications. The default value is 1, which means that an email is sent for every notification.
b. In the Send email regarding notifications to field, type the email address to which this handler sends notifications.
c. In the Set the "From:" address field, type the email address that appears as the
From: address in the email.
For more information about the controls on the Advanced ACE XML Gateway Settings page click the help link at the top of the page.
Step 3 Click the Save Changes button to commit your changes.
The System Management page reappears.
After configuring the email destination, you must enable email notifications for a particular service to have the notifications sent. To do so, in the General Information Settings for the virtual service object for which you want to enable notifications, choose log message body and send notification in the On Error option.
Configuring Global Exception Settings
An exception mapping determines how error messages are mediated between the protocols supported by the ACE XML Gateway. This allows a backend service in SOAP format, for example, to return exceptions that can be understood by a client that uses standard HTTP only.
The mappings associate each type of SOAP fault to an equivalent type of exception in target protocol. The ACE XML Gateway is preconfigured with appropriate mappings; however, in some cases you may want to modify the default mappings to achieve particular results.
Exception mapping can be specified globally or at the service level, for a particular handler/service descriptor pair. When the ACE XML Gateway encounters an error or other exceptional condition, it first checks service-specific (or per-route) mappings. If a mapping is defined for a route that matches the raised exception, the ACE XML Gateway responds with the message specified by the mapping. If there is no per-route mapping, the ACE XML Gateway next searches the currently defined global exception mappings.
The Exception Mapping editor lets you configure exception mediation mappings between the protocols supported by the system. It also allows you to modify the default content of the exception response.
Navigating the Exception Mappings Editor
To view the Exception Mapping editor, click the Exception Mapping Defaults link in the navigation menu. By default, the HTTP protocol exception mappings appear on the page. To view mappings for another protocol, click one of the Mappings for handlers of type links, HTTP, SOAP, TIB/RV, MQ, or Other, to see exception mappings defined for that type of handler.
Notice that runtime exceptions are labelled remote and internal. The remote errors are generated by an external resource, such as a backend server or network. An internal exception is generated by the ACE XML Gateway itself.
This is an important distinction, since there are special configuration options available for exceptions that are generated remotely. In particular, you can choose to have such exceptions passed through or treated as standard response messages, to which normal response processing applies.
Configuring Global Exceptions
This section describes how to specify global exception settings. Global settings apply to any handler for which a specific setting does not exist.
To modify global default exception mappings:
Step 1 As an
Administrator user or as a
Privileged user with the
Routing role in the ACE XML Manager, click the Global Exception Mapping link in the navigation menu.
Step 2 Choose the handler type for which you wish to edit exception mappings by clicking the link at the top of the page from these links: HTTP, SOAP, TIB/RV, MQ, or Other.
For example, to customize exceptions generated by or mapped to service requests to a SOAP 1.1 Document handler, click the SOAP link.
Step 3 Find the type of exception from the listed categories (Access, Network, Protocol, Runtime) for which you wish to edit the exception mapping. Some services permit you to edit exception mappings for both request or response.
Step 4 Click the Customize button next to the exception mapping that you want to edit.
Step 5 For certain types of exceptions that are remotely generated, the following options are available. (Note that the label varies depending on the protocol of the service and handler.)
•Pass the entire error message through exactly as received from the service. No mapping is performed—the exception from the backend is passed through unchanged. With this option selected, the other configuration fields on the page are grayed out.
•Return the following SOAP Fault to the consumer. This is the default behavior, in which an exception from the backend service is regenerated at the ACE XML Gateway as specified by the mapping configuration on the page.
Note For service-specific remote exceptions, you have the added option of processing the exception from the backend system as a standard request, so that all settings applicable to a normal response are applied to the exception message, including, for example, content screening and XSLT processing. For more information, see "Configuring Service-Specific Exception Behavior" section.
Step 6 To specify the error code to return, choose an item from the Map To Response Code menu.
Responses for different handler provide different protocol-specific options. Some protocols may offer multiple response code menus. For example, some SOAP handlers can map an exception to an HTTP response code, a SOAP 1.1 faultcode, and a SOAP 1.2 faultcode.
Step 7 Optionally, edit the default response message.
Some input fields allow you to use the %s variable in the field values. The ACE XML Gateway replaces the variable with the text of the original error message, as received from exception source. At the bottom of the page the editor displays a note indicating whether you may use the %s variable in its text fields.
Step 8 Click Save Changes to commit the new exception mapping to the current policy.
After you change a global exception mapping and deploy the policy, the ACE XML Gateway uses your settings any time it encounters the exception that you edited, unless it occurs in a handler with a more specific configuration for that exception type.
Configuring Service-Specific Exception Behavior
Each route can define its own custom exceptions that override global exception settings for that particular route only, as described in this section. However, this ability is available only for advanced virtual service objects (that is, those that are comprised of a separate handler and service descriptor), not basic virtual services.
Route-Specific Exception Handling
To configure custom exception mapping for a route:
Step 1 Log in to the ACE XML Manager web console as an
Administrator user or
Privileged user with the
Step 2 If necessary, set the active subpolicy to the one that provides the handler to edit.
Step 3 Click the Virtual Services link in the navigation menu.
Step 4 Click the name of the handler to be configured.
The handler's information page appears.
Step 5 Click the edit link in the Custom Exceptions pane of the Routes section, near the middle of the page.
Step 6 In the Custom Route Exceptions page, click the Customize... button that appears next to the name of the exception to customize.
The web console displays an editor for customizing the exception.
Step 7 Use the controls in the exception editor to specify the customized response this handler returns upon encountering the specified exception.
The content of this screen varies according to the exception handler it edits. However, the following options may be available depending on the service and handler type (note that the label varies depending on the protocol of the service and handler):
•Pass the entire error message through exactly as received from the service: No mapping is performed—the exception from the backend is passed through unchanged. With this option selected, the other configuration fields on the page are grayed out.
•Return the following SOAP Fault to the consumer: The default behavior, in which an exception from the backend service is regenerated at the ACE XML Gateway as specified by the mapping configuration on the page. If no option buttons are listed, this is the default behavior. Use the controls in the editor to modify the response code, reason, and message body the handler returns to the client when it encounters a particular exception condition.
A service-level customization adds another option:
•Run response processing on SOAP Fault received from the service. Subjects the exception received from a backend service to normal response processing operations. This makes it possible to process or validate the response by any feature available to a normal response, including XSLT, transformation extension, content screening, and so on.
If set up for response processing, note that the fault response is sent to the client with an HTTP response code of "200 OK." However, other side-effects of a SOAP fault at the ACE XML Gateway are not affected, such as error logging or production of SNMP traps.
Step 8 Click the Save Changes button to commit your changes.
The customized exception handler appears highlighted in Custom Route Exceptions page. Edit and Reset buttons appear in place of the Customize button for the already-customized handler, which are used as follows:
•To modify the custom exception processing further, click the Edit button.
•To restore default handling of this exception, click the Reset button. A dialog box prompts you to confirm your request. If you choose OK, the ACE XML Manager restores the default exception handling behavior to this handler and the Custom Route Exceptions page reflects this change.
Step 9 To exit the Custom Route Exceptions page without making further changes, click the Done button.
The Custom Exceptions pane of the Routes section of the handler information page shows the number of custom exception handlers configured for this route.