The Response Processing Step (SOAP)
The Response Processing step is similar to the Request Processing step. This step specifies how the response message from the native service provider is to be transformed or processed before it is returned to the consuming application.
You may configure and test a virtual service without specifying response processing. You can go back later and specify response processing, if desired.
All steps are optional. You can configure the following steps:
Error Messaging: Configure this step to return a custom error message (and/or the native provider’s service fault content) to the consuming application when the native provider returns a service fault. In addition, you can invoke one or more webMethods IS services to process the error message before and/or after the custom error message is added to the response.
Transformation: Configure this step to perform message transformations using a specified XSLT file.
Use the following procedure to configure the Response Processing step of a virtual service:
To configure the Response Processing step
2. Open the Processing Steps profile.
3. Select the Response Processing tab.
4. Click Add Step, select one of the following steps and click OK.
You can select only one step at a time, but you can go back and select one or more Transform steps, one or more webMethods IS Service steps, but only one Error Messaging step.
Step | Description |
Error Messaging | You use this step to configure error responses for this particular virtual service. Alternatively, you can configure global error responses for all virtual services, using Mediator's Service Fault Configuration page, as described in Administering webMethods Mediator. The precedence of the Error Messaging instructions is as follows: If you configure an Error Messaging step for a virtual service, the error messaging step takes precedence over any settings on the global Service Fault Configuration page. If you do not create an Error Messaging step for a virtual service, the settings on the Service Fault Configuration page take precedence. |
Transform | Configure this step if you want to invoke an XSLT transformation file to transform the SOAP response payloads from XML format to the format required by the consumer. |
webMethods IS Service | |
5. If you selected Error Messaging above, click Error Messaging in the Step list and configure it as follows.
You use this step to configure error responses for this particular virtual service. Select one or both of the following options:
Send Native Provider Fault: When you select this option, Mediator returns the native service provider's fault content (if available) to the consuming application. Mediator will send whatever content it received from the native service provider. If you select this option, the Response option is ignored when a fault is returned by the native service provider. (Faults returned by internal Mediator exceptions will still be handled by the Response option.)
Response: When you select this option, Mediator returns the following fault response 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".
This fault response is returned in both of the following cases:
When a fault is returned by the native service provider.
In this case, the
$ERROR_MESSAGE variable in the fault response will contain the message produced by the provider's exception that caused 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.
Mediator discards the native service provider's fault and does not return this content to the web service caller since it could be considered a security issue, especially if the native provider is returning a stack trace with its response.
When a fault is returned by internal
Mediator exceptions (such as policy violation errors, timeouts, and so on).
In this case, $ERROR_MESSAGE will contain the error message generated by Mediator.
The default fault response contains predefined fault handler variables ($ERROR_MESSAGE, $OPERATION, etc.) which are described in the table below.
You can customize the default fault response using the following substitution variables, where Mediator replaces the variable reference with the real content at run time:
Note: | If you want to reference a custom context variable that you have already defined in a context-based routing rule (as opposed to one you have declared using the Mediator 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 will be the literal string "null". For example, $CONSUMER_APPLICATION will always be "null" if the service's policy does not contain the Identify Consumer action. |
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 date (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 will be present only if the Transport/SOAP Message have user credentials. |
$CONSUMER_APPLICATION | The currently identified consumer application. |
Pre-Processing: Optional. Configure this step if you want to invoke one or more webMethods IS services to manipulate the response message before the
Error Messaging step is invoked. The IS service will 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. For more information, see
Invoking webMethods IS Services in Virtual
Services.
Post-Processing: Optional. Configure this step if you want to invoke one or more webMethods IS services to manipulate the service fault after the
Error Messaging step is invoked. The IS service will have access to the entire service fault and the custom error message. You can make further changes to the fault message structure, if needed. For more information, see
Invoking webMethods IS Services in Virtual
Services.
6. If you selected Transform above, click Transform in the Step list, click Browse and select the XSLT transformation file from your file system, then click OK. If you make changes to the XSLT file in the future, you must re-deploy the virtual service.
7. If you selected webMethods IS Service above, click webMethods IS Service in the Step list and configure it as follows.
Type the fully qualified service name or, to display a list of webMethods IS services that are published to CentraSite, type a keyword phrase in the Service field. The wildcard character * is supported. For example, to return all IS services that start with Test, type Test*. (The list that appears also identifies the application server instance on which each service is located.) Then select one or more services to be used to manipulate the response (the axis2 MessageContext instance) and click OK.
Mediator will pass to the invoked IS service the response message context (the axis2 MessageContext instance), which contains the response-specific information. Thus, you can use the public IS services that accept MessageContext as input to manipulate the response contents. For more information, see
Invoking webMethods IS Services in Virtual
Services.
Note: | The webMethods IS service must be running on the same Integration Server as Mediator. |
8. Configure additional response processing steps if desired, and click Save.
Arrange the steps in the order in which they should be invoked. Use the arrow buttons to rearrange the sequence of steps. To delete a step, select the check box next to the step and click Delete.
