About SOAP Fault Processing

If an error occurs while processing a SOAP request, the response returned to the web service client contains a SOAP fault. You can have the endpoint service signal a fault using one of the following methods:

Specify a fault whose structure is defined by a fault element, using the fault reasons, code, subcodes, node and role that Integration Server generates.
At design time, you can identify the structure of SOAP faults with which an operation can respond by adding fault elements to the operation response in a web service descriptor. Fault elements are optional and can be added to any web service descriptor. For more information, see About SOAP Fault Elements.

To signal a fault that uses one of the fault elements, set up the endpoint service for the operation so that it places an instance document of one of the fault elements into the top level of the service pipeline. The name of the instance document must match the name assigned to the fault element. Integration Server recognizes the fault document in the pipeline, and when generating the fault detail, uses the IS document type defined in the fault element for the structure of the instance document. If the document has a name that matches a fault element, but a different structure, unexpected results will occur.

Integration Server generates a SOAP response that contains a SOAP fault. The SOAP fault contains the detail from the instance document and uses fault reasons, code, subcodes, node and role that Integration Server generates.
Specify a fault whose structure is defined by a fault element, but override the fault reasons, code, subcodes, node and/or role that Integration Server generates.
Set up the endpoint service for an operation so that it places an instance document of one of the defined fault elements into the $fault/detail variable. The name of the instance document must match the name assigned to the fault element. Integration Server recognizes the fault document in the $fault/detail variable, and when generating the fault detail, uses the IS document type defined in the fault element for the structure of the instance document. If the document has a name that matches a fault element, but a different structure, unexpected results will occur.

To override the fault reasons, code, subcodes, node and/or role, set up the endpoint service to also provide the corresponding values in fields within the $fault variable. For a description of the $fault variable, see The $fault Variable.

Integration Server recognizes the $fault variable in the pipeline. Subsequently, Integration Server generates a SOAP response that contains a SOAP fault using the information from the $fault/detail variable. The SOAP fault contains the detail from the instance document and uses values specified for fault reasons, code, subcodes, node and/or role within the $fault variable to override the corresponding values that Integration Server generates.

Note: If there is a top-level instance document for the fault, in addition to the one in the $fault/detail variable, Integration Server ignores the top-level document.
Specify a fault with a structure that was not previously defined using a fault element. Optionally, override the fault reasons, code, subcodes, node and/or role that Integration Server generates.
Although you can identify the structure of SOAP faults in advance, it is not required. To signal a fault at run time, you can add fault information that does not match defined fault elements to the $fault/detail variable in the pipeline. Be sure that the name does not match any defined fault elements. Integration Server recognizes the $fault/detail variable in the service pipeline. Because the document in the $fault/detail variable does not match a defined fault element, Integration Server generates the fault detail without using an IS document type for the structure.

To override the fault reasons, code, subcodes, node and/or role, set up the endpoint service to provide the corresponding values in fields within the $fault variable. For more information, see The $fault Variable.

Integration Server ignores any top-level instance document that might be in the pipeline for a fault. Using the information from the $fault/detail variable, Integration Server generates a SOAP response that contains a SOAP fault. If values are specified for the fault reasons, code, subcodes, node and/or role within the $fault variable, Integration Server uses those values instead of values it generates.

Additionally, faults can occur for the following reasons:

The endpoint service throws a service exception.
In this case, Integration Server constructs a fault message out of the service exception. If the pipeline also contains a $fault variable, Integration Server uses the information specified in the $fault variable to override the fault information.

To make the $fault variable available, you can write a Java service that throws a ServiceException, but before throwing the exception, places the $fault variable in the pipeline.

Alternatively, for a flow service, you can use the EXIT with failure construct. As a result, before exiting the flow service with a failure, you can place the $fault variable into pipeline.
A request handler service ended in failure and signaled that a fault should be generated.
When the request handler returns a status code 1 or 2, Integration Server generates a SOAP fault, along with the fault code, subcodes, reasons, node, and role for the fault. You can use the pub.soap.handler:updateFaultBlock service to modify the code, subcodes, reasons, node, and/or role that Integration Server generates.

Note: When the request handler returns status code 3, you are expected to build the SOAP fault. As a result, the pub.soap.handler:updateFaultBlock service is not necessary.

You can invoke the pub.soap.handler:updateFaultBlock service in a response or fault handler to update the fault created due to the failure in the request handler chain. For more information about using the service, see Modifying a Returned SOAP Fault. For more information about handlers, see the Web Services Developer’s Guide .

About SOAP Fault Elements

To identify the information to provide in a SOAP fault at design time, you add fault elements to the operation response in a web service descriptor. The fault element, which is an IS document type, describes the expected structure of the Detail element in the SOAP fault. Fault elements are optional and can be added to any web service descriptor.

When you create a service first provider web service descriptor, add fault elements to represent the SOAP faults that an operation in the web service descriptor might return. If an error occurs at run time, the underlying service that corresponds to the operation can signal a fault by returning an instance document for one of the IS document types used as a fault element. Integration Server recognizes the fault document in the service pipeline and subsequently generates a SOAP response that contains a SOAP fault. Within the SOAP fault, the Detail element contains the fault document.

When you create a WSDL first provider web service descriptor or a consumer web service descriptor, Integration Server creates an IS document type for each message element in the source WSDL document. If an operation in a WSDL defines a soap:fault element, Integration Server generates an IS document type for the fault element.

In a consumer web service descriptor, the web service connector that corresponds to the operation includes logic to detect the fault element in the SOAP response. Integration Server then places the contents of the fault document into the detail document in the output parameter. The structure of the detail element matches the structure of the IS document type used as the fault element.

Note: The structure of the SOAP fault returned by the web service connector depends on the version of Integration Server on which the web service descriptor was created. For more information, see Web Services Developer’s Guide .

It is possible for a web service to return a fault that does not appear in a WSDL file. To account for these SOAP faults, you can add fault elements to a WSDL first provider web service descriptor or a consumer web service descriptor. For more information, see Adding a Fault Element to an Operation.

Adding a Fault Element to an Operation

About this task

Keep the following points in mind when adding fault elements to an operation:

You add fault elements to an operation response.
The fault document must be an IS document type.
You must set up a package dependency if you use an IS document type from a different package as a fault.
If you add a fault to an operation that uses an In-Only Message Exchange Pattern (MEP), the MEP will change to Robust In-Only MEP. For more information about message exchange patterns, see the Web Services Developer’s Guide .

To add a fault element to an operation

Procedure

In Package Navigator view, open and lock the web service descriptor to which you want to add a fault element.
In the Operations tab, expand the operation and the response to which you want to add the fault element.
Select the Fault icon and click (Add Header or Fault button) on the web service descriptor editor toolbar.

Because a fault was selected when you clicked this button, Designer displays the default document selector dialog.
Select the IS document type to use as the fault element. Click OK.
If you want to change the name of the fault element, with the fault element selected, in the General category of the Properties view, update the Name property.
Click File > Save.

Important: When you add a fault to a consumer web service descriptor, you must refresh the web service connector(s). See Refreshing a Web Service Connector.

Results

Notes:

If you add a fault element to an operation in a consumer web service descriptor, and then refresh the web service connector, Integration Server updates the logic of the web service connector to look for and handle the fault at run time.
If you add a fault element to an operation in a WSDL first provider web service descriptor, the WSDL document generated from the provider web service descriptor will include the new faults as soap:fault elements in the operation.
You can add multiple fault elements to an operation in a web service descriptor. At run time, if the service that corresponds to the operation returns multiple fault documents, the SOAP fault in the resulting SOAP response will contain only one fault document. Specifically, Integration Server returns the fault document that is an instance of the IS document type that appears first in the operations list of fault elements.
For example, suppose that an operation had three fault elements listed in this order: faultA, faultB, and faultC. Note that each fault element corresponds to an IS document type of the same name. At run time, execution of operation (service) results in two fault documents—one for faultB and one for faultC. In the SOAP response generated by Integration Server, the SOAP fault contains the faultB document only.

The $fault Variable

Use the $fault variable to override values Integration Server generates for a fault. To do so, specify the fault detail in the $fault/detail variable. Then, to override the fault reasons, code, subcodes, node and/or role, provide the corresponding values.

The following shows the structure of the $fault variable.

Variable	Description
`$fault`	Document Fault information that overrides other fault information in the service pipeline, if any.
	`code`	Document Optional. The fault code and possible subcodes. Integration Server uses values you specify to modify the fault code and subcodes it generates for the fault. Note: For a SOAP 1.1 fault, Integration Server ignores any values specified for `subcodes`.
		`namespaceName`	String The namespace name for the SOAP fault code.
		`localName`	String A code that identifies the fault.
		`subcodes`	Document List Optional. Subcodes that provide further detail. Each Document in the `subCodes` Document List contains: `namespaceName` for the subcode `localName` that identifies the subcode
	`reasons`	Document List Optional. Reasons for the SOAP fault. Integration Server uses values you specify to modify the reasons it generates for the fault. Note: For a SOAP 1.1 fault, if you specify more than one reason, Integration Server uses the first reason. Multiple reasons are supported for SOAP 1.2 faults.
		`@lang`	String Language for the human readable description.
		`*body`	String Text explaining the cause of the fault.
	`node`	String Optional. The URI to the SOAP node where the fault occurred. Integration Server uses value you specify to modify the node it generates for the fault. Note: For a SOAP 1.1 fault, Integration Server ignores any values specified for `node`.
	`role`	String Optional. The role in which the node was operating at the point the fault occurred. Integration Server uses value you specify to modify the role it generates for the fault.
	`detail`	Document Fault information you want Integration Server to use. This overrides any top-level instance document that defines the fault detail.

Modifying a Returned SOAP Fault

If a provider or consumer web service results in a fault, you can modify values in the fault, if needed. For example, you might want to alter the fault code if your error handling requires a specific code.

To update a SOAP fault, use the pub.soap.handler:updateFaultBlock service. For more information about this service, see the webMethods Integration Server Built-In Services Reference . You can invoke the updateFaultBlock service from a response handler or fault handler service for a web service provider. Use the service to customize one or more of the following SOAP fault fields:

Fault field you can customize	Notes
fault code and subcodes	For a SOAP 1.1 fault, if you specify subcode values, the service ignores them because subcodes are only applicable for a SOAP 1.2 fault.
fault reasons	For a SOAP 1.1 fault, if you specify more than one reason, the service only uses the first reason. Multiple reasons are supported for SOAP 1.2 faults.
fault node	For a SOAP 1.1 fault, if you specify a value for node, the service ignores it because the fault node is only applicable for a SOAP 1.2 fault.
fault role	The fault role is supported for both SOAP 1.1 and SOAP 1.2 faults.