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.

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.

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.