Software AG Products 10.11 | Using CentraSite | Runtime Governance | Run-Time Policy Management | Built-In Run-Time Actions Reference (CentraSite Business UI) | Built-in Actions for Run-Time Policies (CentraSite Business UI) | Conditional Error Processing
 
Conditional Error Processing
This action returns a custom error response (and the native provider’s service fault content) to the client when the native provider returns a service fault. You can configure conditional error processing and use variables to create custom error messages. This action also allows you to define error messages based on content types: text, XML, and JSON.
Alternatively, you can configure global error responses for all APIs, using Mediator's Service Fault Configuration page (see Administering webMethods Mediator).
Note:
To enable support for conditional error processing in CentraSite, add an entry in the centrasite.xml customization file as follows:
<Action name="ConditionalErrorProcessing" id="uddi:61849291-3bad-4612-819b-5fe5a6b4e958" occurrence="*"></Action>
You can find this file on <CentraSiteInstall_Directory>\cast\cswebapps\BusinessUI\custom\conf.
Input Parameters
Error Conditions
Specifies the error conditions and how each of these error conditions are to be processed. You can define a maximum of three conditions. You can configure only one error condition per type. For example, you cannot define two status code conditions. To specify multiple conditions, use the plus button to add rows.
Type
Value
Description
Status Code
(Default). Specify the error status code. For example: 400, 500.
HTTP Header
Specify the details of the custom HTTP header(s) included in the client requests. The parameters are:
*HTTP Name String. Specifies the name of the HTTP header.
*HTTP Value String. Specifies the value of the HTTP header.
XPath Expression
Specifies the details of the XPath expression in the API request. The parameters are:
*XPath Expression
*Namespaces: Specifies the namespace of the XPath expression. To specify multiple XPath expressions, use the plus button to add rows.
*Prefix: The prefix for the namespace. For example,soapenv or axis
*URI: The namespace URI - For example, http://schemas.xmlsoap.org/soap/envelope/ or http://ws.apache.org/axis
*Value: Specifies the value of the XPath expression.
Pre-Processing
Specifies how the native service error response is to be processed before sending the same to Mediator. You can configure multiple ESB and XSLT processing steps. You can either log the error message sent by the native service without any changes or you can remove any critical information that you do not want Mediator to log or send to the client. The processing of these steps is taken up in the order in which they are configured.
Value
Description
XSLT
(Optional). (String). Specify the XSLT file that you want to use to transform the service error response. Use the select button to browse to and select a file.
ESB
(Optional). (String). (Default). Specify the webMethods IS Service.
Invokes one or more webMethods IS services to manipulate the response message from the native API before it is returned to the consuming application. The IS service have access to the response message context (the axis2 MessageContext instance) before it is updated with the custom error message. For example, you might want to send emails or perform custom alerts based on the response payload.
Failure Message
String. Specify the custom failure message that Mediator should send to the client. You can configure an error template each for the content types: Text, XML, and JSON. For addition details, see the fault handler variables listed in the table below. For example, $CONSUMER_APPLICATION $OPERATION :$ERROR_MESSAGE.
Value
Description
Content-Type
Specifies the content type for which the failure message is defined. You can select the following content types:
*text
*xml
*json
Note:
You can define only one error template per content type.
Error Template
Specifies the content of the error template to use. You can use predefined fault handler variables to create the error template. A list of the predefined variables is available in the table below.
Use as Default
Specifies the error template to use as the default.
Custom Error Variables
Specify the error variables to be used in the custom error message. To specify multiple error variables, use the plus button to add rows.
Payload Type
Select the payload type.
Value
Description
Request
Selects the request payload type.
Response
Selects the response payload type.
Name
Specifies the name of the payload.
XPath Expression
Specifies the details of the XPath expression in the API request.
Namespaces
Specifies the namespace of the XPath expression. To specify multiple namespaces, use the plus button to add rows.
Prefix
The prefix for the namespace.
URI
The namespace URI.
Post-Processing
You can configure multiple ESB and XSLT processing steps. You can either log the error message sent by the native service without any changes or you can remove any critical information that you do not want Mediator to log or send to the client. The processing of these steps is taken up in the order in which they are configured.
Value
Description
XSLT
(Optional). (String). Specify the XSLT file that you want to use to transform the service error response. Use the select button to browse to and select a file.
ESB
(Optional). (String). (Default). Specify the webMethods IS Service.
Invokes one or more webMethods IS services to manipulate the API fault after the Conditional Error Processing action is invoked. The IS service has access to the entire API fault and the Conditional Error Processing message. You can make further changes to the fault message structure, if needed.
Send Native Provider Fault Message
When the parameter is enabled, Mediator sends the native SOAP or REST failure message to the client. When you enable this parameter, the Failure Message is ignored when a fault is returned by the native API provider. (Faults returned by internal Mediator exceptions are handled by the Failure Message.)
Failure Messages
The failure message is returned in both of the following cases:
*When a failure is returned by the native API provider.
In this case, the $ERROR_MESSAGE variable in the failure message contains the message produced by the provider's exception that caused the error. This is equivalent to the getMessage call on the Java Exception.
*When a failure is returned by internal Mediator exceptions (such as policy violation errors, timeouts, and so on).
In this case, $ERROR_MESSAGE contains the error message generated by Mediator.
Alternatively, you can configure global failure messages for all APIs, using Mediator's Service Fault Configuration page, as described in Administering webMethods Mediator.
Mediator returns the following failure message to the consuming application:
Mediator encountered an error:$ERROR_MESSAGE while executing
operation:$OPERATION service:$SERVICE at time:$TIME on date:$DATE.
The client ip was:$CLIENT_IP. The current user:$USER.
The consumer application:$CONSUMER_APPLICATION".
The precedence of the failure message configurations is as follows:
*If you configure a Conditional Error Processing action for an API, the failure message configurations take precedence over any settings on the global Service Fault Configuration page.
*If you do not configure a Conditional Error Processing action for an API, the settings on the Service Fault Configuration page take precedence.
The default failure message contains predefined fault handler variables ($ERROR_MESSAGE, $OPERATION, and so on.).
You can customize the default failure message using the following substitution variables, where Mediator replaces the variable reference with the real content at run time:
*The predefined context variables listed in Context Variables in Virtual Services.
*Custom context variables that you declare using Mediator's API .
Note:
If you want to reference a custom context variable that you have already defined in a virtual API, you must add the prefix $mx to the variable name in order to reference the variable. For example, if you defined the variable TAXID, you would reference it as $mx:TAXID.
The fault handler variables are described below.
Note:
If no value is defined for a fault handler variable, then the returned value is the literal string null. For example, $CONSUMER_APPLICATION is always null if the service's policy does not contain at least one of the Evaluate actions.
Fault Handler Variable
Description
$ERROR_MESSAGE
The error message produced by the exception that is causing the error. This is equivalent to the getMessage call on the Java Exception. This maps to the faultString element for SOAP 1.1 or the Reason element for SOAP 1.2 catch.
$OPERATION
The operation that was invoked when this error occurred.
$SERVICE
The service that was invoked when this error occurred.
$TIME
The time (as determined on the Container side) at which the error occurred.
$DATE
The date (as determined on the Container side) at which the error occurred.
$CLIENT_IP
The IP address of the client invoking the service. This might be available for only certain invoking protocols, such as HTTP(S).
$USER
The currently authenticated user. The user presents only if the Transport/SOAP Message have user credentials.
$CONSUMER_APPLICATION
The currently identified consumer application (client).
$NATIVE_STATUS_CODE
The HTTP error status code that is returned by the native service.