This is a revised SOAP Fault Proposal, originally proposed by Christine.

----------------------------------

Handling Failures. ----------------------------------

SOAP Fault MUST be used only when an error or errors occurred outside DSML. For example, when processing

between SOAP Server to a DSML server/gateway. SOAP Fault should not be used to communicate failures

inside the DSML system. errorResponse and LDAP errors are the examples of failure originating from within DSML.

When SOAP is used to transport DSML document, there are three potential failure points:

1) Communication between SOAP and DSML. For example DSML server/gateway is not responding to SOAP server. In this case, SOAP server should return SOAP Fault.

(Please note: SOAP and DSML can be implemented in the same server or component.)

Example:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">

<SOAP-ENV:Body>

<SOAP-ENV:Fault>

<faultcode>SOAP-ENV:Server</ faultcode>

<faultstring>Fatal error: DSML gateway is not responding</ faultstring>

</SOAP-ENV:Fault>

</SOAP-ENV:Body>

</SOAP-ENV:Envelope>

In addition to this scenario, SOAP client may transmit an invalid SOAP message, in this case, SOAP server responds with SOAP Fault.

This specific scenario is outside the scope of the specification. Please consult the latest SOAP specification for this matter.

Example:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">

<SOAP-ENV:Body>

<SOAP-ENV:Fault>

<faultcode>Client.ERR_SOAP</ faultcode>

<faultstring>

Check SOAPAction header..."http://test-uri"

'Body' element expected

Fatal error:not valid SOAP message

</ faultstring>

</SOAP-ENV:Fault>

</SOAP-ENV:Body>

</SOAP-ENV:Envelope>

2) As it mentions in the DSMLv2 specification, a client may produce a request document that is syntactically incorrect, i.e. does not conform to dsmlEnvelopeRequest schema. In this case the DSMLv2-based server still produces a response document, and the response document should be included as part of SOAP Body.

Other scenario could be where a DSML gateway can not establish a connection to the target LDAP server.

Example:

<se:Envelope xmlns:se='http://schemas.xmlsoap.org/soap/envelope/'>

<se:Header/>

<se:Body>

<dsml:dsmlEnvelopeResponse xmlns:dsml="urn:oasis-open:dsml:2">

<dsml:errorResponse

type="couldNotConnect">

<dsml:message>Cannot connect to a DSML server</dsml:message>

</dsml:errorResponse>

</dsml:dsmlEnvelopeResponse>

</se:Body>

</se:Envelope>

3) A failure or failures may occur during LDAP operations. In DSMLv2, it is expressed in the LDAPResult with a ResultCode

corresponding to any LDAPErrorCode other than: 'success', 'compareFalse' or 'compareTrue'. As with (2), DSMLv2 response document should be included in SOAP body

Example:

<se:Envelope xmlns:se='http://schemas.xmlsoap.org/soap/envelope/'>

<se:Header/>

<se:Body>

<dsml:dsmlEnvelopeResponse xmlns:dsml="urn:oasis-open:dsml:2"

xmlns:batch="urn:oasis-open:dsml:2:batch">

<dsml:modifyResponse>

<resultCode code="53" descr="unwillingToPerform"/>

<errorMessage>System Attribute may not be modified</errorMessage>

</dsml:modifyResponse>

<dsml:addResponse>

<resultCode code="0"/>

</dsml:addResponse>

<dsml:naddResponse>

<resultCode code="0" descr="success"/>

<control>...</control>

<control>...</control>

</dsml:addResponse>

</dsml:dsmlEnvelopeResponse>

</se:Body>

</se:Envelope>